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1.0 Welcome to EMPOWER/CS 

Welcome to EMPOWER/CS, PERFORMIX Inc.'s full-featured solution for efficient 
client/server load testing. With EMPOWER/CS, you can emulate multiple users 
from a single load testing machine to accurately measure response time and 
throughput of your client/server environment. EMPOWER/CS captures and 
replays actual client/server activities running from Microsoft Windows PCs. It 
stress tests applications and the database server by emulating multiple PCs that 
interact with the server and then measures client/server performance by 
summarizing response times. 

Until now, client/server load testing required assembling individual PCs for each 
system-supported user, which could involve up to hundreds or thousands of PCs; 
With EMPOWER/CS, this costly and cumbersome process is reduced to one UNIX 
driver machine that emulates as many PCs needed to test your entire client/server 
environment. 

You can use EMPOWER/CS to load test your client/server applications during the 
entire cycle of development, to determine your database servers performance 
under peak load conditions, and to help determine future needs of your 
client/server environment. 

This User's Guide is designed to help you understand the testing processes and 
capabilities of EMPOWER/CS and to guide you through efficient client/server load 
testing. 




1.1 Organization of the EMPOWER User's Guides 

The complete documentation for EMPOWER/CS includes three user's manuals 
which contain general use information, installation instructions, technical reference 
material, and examples. The following list identifies each user manual; 
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EMPOWER/CS Script Development 

Describes how to create and execute scripts to perform realistic load tests on your 
client/ server, environment. This process involves using the EMPOWER/CS tools, 
Capture and Cscc, and editing and enhancing your scripts 

Multi-User Testing 

Describes how to use the multi-user tools Mix, Extract, Report, Draw, Monitor, and 
Global Variables (GV) for emulating realistic loads and measuring performance 

Reference 

Describes commands, functions, and possible error messages for EMPOWER/CS. 
This manual also includes information for contacting PERFORMIX technical support 



1.2 Organization of this Manual 



EMPOWER/CS Script Development is divided into the following sections: 



- -3F 



Section 1: 
Section 2: 

Section 3: 

Section 4: 

Section 5: 

Section 6: 
Section 7: 

Section 8: 



Welcomes you to EMPOWER/CS 

Introduces you to EMPOWER/CS and load testing for 
client/server environments 

Outlines the procedure for installing EMPOWER/CS and 
setting up the testing environment 

Describes the EMPOWER/CS tool, Capture, which 
captures user and PC activities to build executable scripts 

Describes the EMPOWER/CS tool, Cscc, which compiles 
your scripts into an executable format 

Describes the processes for executing scripts 

Describes script content and methods for editing your 
scripts including step-by-step examples 

Describes the EMPOWER/CS Windows tools 
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13 User's Guide Conventions 



The conventions followed in this User Guide are listed below: 



Regular Font 
Arial Font 

Mono-spaced Font 

Bold mono- spaced font 

[-S scriptid] 

(I) 



Endf unction ( ) 



Parse ( ) 



cscc 



Capture 



Used for all regular body text 

Represents elements of the MS Windows 
environment such as pushbuttons, window titles, 
user entries, etc. 

Used for ail command, function, and file names; for 
all examples; and, generally, for any computer 
generated text 

In examples, represents entries made by the 
EMPOWER/CS user 

In command syntaxes, text within these square 
brackets represents optional command parameters 

Vertical lines separate command parameter choices 

Within scripts, the ellipsis marks indicate that some 
script content was left out for brevity 

Parentheses are included with script functions 
mentioned in regular body text For most functions, 
one or more parameters will be listed in the 
parentheses when the function is used in a script 

EMPOWER/CS script functions use initial 
capitalization 

EMPOWER/CS command names use all lowercase 
letters 

When an EMPOWER/CS tool is mentioned within 
regular body text, it is shown in regular font with 
initial caps 
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The term, "SUT," refers to your client/server system under test The client/ server 
SUJ includes the database server and the database(s) on that server used for your 
emulation. 
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2.0 Introduction to Load Testing with 

EMPOWER/CS 

EMPOWER/CS tests the performance of a client/server application or system by 
emulating application activity of multiple PC users and by gathering response time 
data. Using EMPOWER/CS eliminates the need for many PCs to stress test your 
client/server system under test (SUT) because you can emulate multiple PC users 
on a single UNIX driver machine applying a realistic load to the SUT. 
EMPOWER/CS tools allow you to capture actual user activity in a script file, 
combine and execute several scripts at once, and collect performance statistics. 



01 

^ 2.1 Why Use EMPOWER/CS? 

p You can use EMPOWER/CS to support applications development, computer 

» purchase decisions, capacity planning, and product demonstrations. 



2.1.1 Applications Development 

After you develop an application, most problems do not arise until your customer 
tries to use the application during peak load conditions. Load testing with 
EMPOWER/CS measures the true scalability and performance of new 
client/ server applications and systems before they are introduced to actual users. 
By emulating multiple users with EMPOWER/CS, you can identify problems and 
defects from the very beginning of the development cycle up to new releases of 
the product 



Companies that do not load test their client/server products risk introducing 
applications to the marketplace that fail to meet critical user expectations. 
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EMPOWER/CS prevents such costly weaknesses in fielded applications, thus, 
improving software quality and customer satisfaction. 



2.1.2 Computer Purchase Decisions 



m 



The lack of practical load testing tools has posed a serious dilemma for companies 
wishing to migrate from a mainframe system to a client/server environment. 
EMPOWER/CS reduces this costly load testing process to one driver machine, 
allowing you to test a system efficiently. You can apply your current and future 
client/ server workloads before purchasing an application or system. 

EMPOWER/CS provides price performance information by determining the 
number of client/server transactions per unit time for specified user activities. For 
instance, you can determine how long it takes to perform the same query for ten, 
one hundred, or even one thousand users. Evaluators may use such data and cost 
information associated with software and users to determine the value of the 
client/server system under test (SUT) in terms of dollars per transaction. 
EMPOWER/ CS is more valuable than other evaluation tools because it generates 
data that characterizes your application. 



2.1.3 Capacity Planning 

EMPOWER/CS can estimate the amount of processing power needed to meet 
your future load requirements by performing tests that replicate both the current 
and future workloads of your client/server environment. Load testing can be 
executed on your current system to determine if your system must grow with your 
planned workload. 
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2.1.4 Product Demonstrations 

EMPOWER/CS is highly effective in demonstrating your client/server product or 
application to potential customers. A performance test, emulating actual user and 
database activity provides your customers with a feeling of confidence that your 
client/server application will perform in the field as promised. This is especially 
useful if you do not have reference sites for your potential customers' workload. 



2.2 How Does EMPOWER/CS Work? 

f=Vz 

5 EMPOWER/CS places a capturing agent on a Microsoft Windows PC that records 

y*j dialog between the PC and the SUT. From this interaction, the capturing agent 

M builds a script that is suitable for executing multi-user tests: 




Script 



EMPOWER/CS-Vl.O.1 



2-3 



Copyright PERFORMIX. Inc. © 1995 




User's Guide— Script Development 



Because EMPOWER/CS requires the multi-tasking features of UNIX to run multiple 
scripts, scripts are transferred to a UNIX driver machine where they are compiled 
and executed. With EMPOWER/CS, the UNIX driver can combine and execute 
several scripts simultaneously, and the scripts can be edited and enhanced to 
emulate more realistic client/server activity. Only the UNIX script driver and your 
SUT are required for the emulation. 

When the script is executed on the UNIX script driver, it acts as a client to interact 
with the SUT emulating captured PC activities. As the script executes, the SUT 
assumes it is servicing SQL requests from an actual PC, thus, creating a true multi- 
user test environment: 




UNIX Script Driver SUT 
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% 2.3 Testing Process 

The first step for load testing your client server environment with EMPOWER/CS 
is capturing PC and SUT interactions into a script file. When capturing scripts, 
changes to your client/ server application are not required. The capturing tool only 
requires that you perform the most common user activities. To build complete 
scripts, EMPOWER/CS records mouse and keyboard strokes, SQL requests to the 
SUT, and data returned to the PC. The resulting scripts are transferred to the UNIX 
script driver. 

Before executing scripts, you must compile them on the UNIX driver machine. The 
executing script binary replaces the PC to interact with the SUT. 
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Then, to simulate the actual load on the. client/server environment, you should 
combine and execute multiple scripts. You can duplicate individual scripts to 
simulate multiple users performing similar activities, and you can combine different 
scripts to emulate a complex set of user and application activity. 

To produce the most accurate test results, you can edit your scripts to make them 
unique to your environment. Because EMPOWER/CS scripts are actually C 
language programs, they can be enhanced or supplemented as required. You can 
vary scripts by branching, altering data, and inserting loops. You also can change 
values entered in queries and updates during Capture (because in reality, all users 
would not query and update identical records continuously). User entries can be 
substituted by generating random values, sharing pools of input on the driver, 
accessing data returned from the SUT, or passing data between the scripts. 

You can control the rate of transactions applied to the SUT while tests execute. 
Such controls as typing rate, thinking delays, constant and variable pacing, and 
synchronization points can be set at the start of a test and then adjusted as needed 
Adjusting controls during the test permits load balancing and tuning. 

While tests are running, you can monitor scripts to verify progress, debug running 
scripts, and examine current response times. After your tests execute, you can 
generate reports that summarize interactive response time and peak throughput 
supported by your system. Valuable performance information such as response 
time averages, minimums, maximums, percentiles, transaction categories, and client 
processing times can be assembled within minutes. 



2.4 EMPOWER/ CS Tools 

EMPOWER/CS includes and uses the following tools: Capture, Cscc, Mix, Extract, 
Report, Draw, Monitor, and Global Variables. 



EMPOWER/CS-Vl.O.1 



2-6 

Copyright PERFORMIX. Inc. 0 1995 



User's Guide— Script Development 



2.4.1 Capture 

Capture is executed from Microsoft Windows on your PC to capture actual PC and 
SUT interactions in a script file. You simply activate the Capture icon, perform the 
user activity you wish to test, and then transfer your captured script file to the UNIX 
driver. Many options are available when capturing your script such as inserting user 
think times into the script file, adding comments and functions to the script, and 
automatically transferring scripts to the UNIX driver. The following example depicts 
the Capture command window. 



*0 



Capture 



File Help 




A sample EMPOWER/CS script file, scriptl.c, follows. Such user and database 
activity as mouse events, logging on to the database, and processing a query were 
captured into this script (Some script content was left out for brevity): 
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/* EMPOWER/CS VI. 0.1 Remote Terminal &rtulator Script */ 



Typerate(5) ; 
Pointerrate(150) ; 
ThinJcuniformd, 2 .5) ; 
Seed(getpid() ) ; 
Timeout(300, COOTINUE) ; 
Dberror (COOTINUE) ; 
Unset (NOTIFY) ; 

Beginscenario ( " scriptl - ) ; 



/* Typing delay in CPS */ 
/* Pointerrate in PPS */ 
/* Think delay */ 

/* Seed random number generator V 

/* What to do if DB transaction takes too long */ 

/* What to do on Database errors */ 

/* Don't display warnings. I'll use Mon to find them */ 



InitialWindow(0, "Desktop" , 0, 0, 640, 480) ; 
InitialWindow(l, "MS-DOS Prompt" , 21, 408, 0, 0) ; 
InitialWindow(2, "File Manager" , 89, 108, 598, 469) ; 
InitialWindow(3, "Program Manager" , 36, 26, 545, 333) ; 



LeftDblPress(249,121) ; 

WindowRcv("Pt") ; 

AppWait(1.21) ; 
WindowRcvt "CoCwAcSfPt" ) ; 

CurrentWindow ( "Qnployees" , 44 , 44, 636 , 408) ; 

Think(2.31) ; 

LeftButtonPress{62,78) ; 



AppWait(0.22) ; 

WindowRcvCSfAcSfDwDwAcSfSfSfPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPt" ) ; 
WindowRcvCPtPtPtPtPtPtPtPtPtPt") ; 

CurrentWindow ("Program Manager" ,36,26, 545, 333) ; 

SysKey Press (VK_MENU) ; 

Type("fr") ; 

AppWait<0.06) ; 

WindpwRcv( "CoCwCwOX>a<>/C\s/C^ ; 

CurrentWindow ( "Run" ,72,77,450, 238) ; 

Type("c:\\acct\\acct~M") ; 
WindowRcv ( " CwCwCwCwCwCwCw " ) ; 



( continued on following page ... ) 
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Openenv { ORACLE , VERSIONV6V7 ) 




Username(LOGl, "scott/tigeresUT" ) ; 


Password (LOG1, ■ ") ; 




Logon ( ORACLE , LOG1 ) ; 




WindowRcv ( - SfAcSf Sf Sf DwPt " ) 




Currentwindowt" Program Manager" , 36, 26, 545 , 333) ; 


Open (LOG1 , CURl ) ; 




AppWait(4.84) ; 




WindowRcv { "AcSf Pf ) ; 




CurrentWindow ( - Accounts ",147,66,533,360); 


But tonPush ( " Payable ",267,213); 


AppWait(O.OS) ; 




WindowRcv! "Sf PtO^X^sCvX^CwCwOX^CwCwCwCw ; 


Begintimer ( "Accounts_Payable" ) ; 


Dbset (CURl , DEFER, TRUE) ; 




Parse (CURl, " SELECT ID, FIRST_NAME, LAST_NAME , ADDRESS_LINE_1 , ADDRESS_LINE_2 , 


ADDRESS_LINE_3 , PHONE_NUMBER , FAX_NUMBER, COMM_PAID_YTD , ACCOUNT_BALANCE , COMMENTS 


FROM CUSTOMERS " ) ; 




DescribeAlKCURl, 1, 12); 




Dbset (CURl, MAXARRSIZE, 64) 




DefinetCURl, "1", STRING, 40); 


Define (CURl, "2", CHAR, 21) 




Define(CURl, "3", CHAR, 21) 




Define(CURl, "4", CHAR, 21) 




Define(CURl, "5", CHAR, 21) 




Define(CURl, "6", CHAR, 21) 




Define(CURl, "7", CHAR, 16) 




Define (CURl, "8", CHAR, 16) 




Define(CURl, "9", STRING, 40); 


Define (CURl, "10", STRING, 40); 


Define(CURl, "11", CHAR, 241); 


Exec (CURl) ; 






( continued on following page . . . ) 
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Dbset(CURl, FETCHSIZE, 64); 
Fetch (CURD; 

while (GetNextRow {CUR1 > ! =NOMOREROWS) ; 
Endtimer (Accounts_Payable) ; 



Begintimer( "Accounts" ) ; 
Commit (LOG1) ; 



WindowRcv("PtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPt") ; 

Close (CURD ; 
Logoff (LOG1) ; 
Closenv (ORACLE) ; 

Endtimer ( "Accounts" ) ; 

Endscenar io ( " script 1 " ) ; 



2.4.2 Cscc 

After the script file has been transferred to the UNIX driver, you should compile 
the script into a machine language version. The Cscc tool compiles the script which 
can be executed at the command line. Because the script is a C language program, 
additional C language statements can be added to enhance the script In the 
following example, we will compile the script file examplel.c into an executable 
binary: 

$ cscc scriptl 

The script now can be executed from the command line: 



$ scriptl 
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2.4.3 Mix 



Mix emulates an actual multi-user environment by executing multiple scripts after 
they are compiled by Cscc. A script table and, optionally, a command file specify the 
number of users to emulate, the name of the script or scripts each user will 
execute, delay times between the start of each script, and the termination condition 
of the test. Each script that executes produces a log file used for preparing 
statistical reports. 



In the following examples, suppose you have created four scripts. Your mix table, 
tablel, could look like the following: 



userl, query logl 

user2, update log2 

user3, accounts log3 

user4 , customer log4 



With Mix, these scripts can be executed in a multi-user test 



$ mix 

Mix: EMPOWER/CS VI. 0.0, Serial#R00OO0-000 , Copyright PERFORMIX, Inc. 
1988-95 

mix> use tablel 
mix> start all 
[userl] started 
[user2] started 
[user3] started 
[user4] started 

mix> userl terminated (3/4) running 
user2 terminated (2/4) running 
user 3 terminated (1/4) running 
user 4 terminated (0/4) running 

mix> quit 
$ 
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2.4.4 Reports 

Generating performance reports from one or more executed scripts is 
accomplished in two steps. First, you must use the Extract tool which parses each 
script s log file and records response time information in a set of flat ASCII files. 

$ extract logl.l log2 . 1 log3.1 log4.1 

The Report tool then uses these ASCII files to produce statistical reports that 
describe response time and system throughput (Note: You also may generate 
reports from your own statistical or graphics programs,) Report will generate an 
EMPOWER/CS standard report similar to the following: 

__ 





$ report 






OS 


EMPOWER Standard Report 




M 


Date: 


Fri Jan 27 14:49:14 1995 




Start time: 


14:42:42 






Stop time: 


14:43:23 






Duration: 


00:00:41 






Mix: 


4 users 






Unit: 


seconds 




M= 


Scenario 


Total Finish Thruput 


Median Average Minimum Maximum Std-Dev 




query 


1 1 0.02 


31.26 31.26 31.26 31.26 0.00 


ly 


update 


1 1 0.02 


22.07 22.07 22.07 22.07 0.00 




accounts 


1 1 0.02 


30.95 30.95 30.95 30.95 0.00 




customer 


1 1 0.02 


22.18 22.18 22.18 22.18 0.00 


^=$? 


Overall 


4 4 0.10 


26.56 26.62 22.07 31.26 4.49 




Function 


Total Finish Thruput 


Median Average Minimum Maximum Std-Dev 




logoutl 


2 2 0.05 


4.35 4.35 4.33 4.36 0.01 







2.4.5 Draw 

Draw accepts one or more EMPOWER/CS reports to produce bar charts that depict 
relationships among performance results. These relationships can summarize a 
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single multi-user test or a series of multi-user tests in which each test contained a 
different user level or system configuration. The following example is a typical 
EMPOWER/CS bar chart 



Scenario Response Time 



Start time 
Stop time 
Duration 
Mix 

Input file 
32.5 +- - 



14:42:42 
14:43:23 
00:00:41 
4 users 
report . STD 



Legend: 

* - Average 



R 
e 
s 

P 
o 
n 
s 
e 

T 
i 
m 
e 



30.0 + * 



27.5 +- 



25.0 +- 



22.5 +- 



20.0 + * *- 



Scenario 





Scenario 


Response Time 


ID 


Description 


Average 


A 


query 


31.26 


B 


update 


22.07 


c 


accounts 


30.95 


. D 


customer 


22.18 
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2.4.6 Monitor 

Monitor displays critical user information on your UNIX script driver during multi- 
user emulations. Information is listed in logically grouped views that can be sorted 
on any field in the view. With this tool, you can monitor response times, control 
script execution, track and correct script errors and timeouts, and view test 
progress. You also can identify and debug problem scripts, verify system load, and 
take a "snapshot" of user activity during a system bottleneck. Commands are 
provided to suspend, resume, or kill executing scripts during the multi-user test. 



r=5 



Fri Jan 27 14:42:58 

View 1 of 7 Script 1 of 4 



EMPOWER/CS MONITOR VI . 0 (c) PERFORM IX, Inc. 1995 

Running Scriptid Sorting ^ Interval 5 



Scriptid Script State __ LastEvent 

userOOl query bpush ><ButtonPush><ButtonPushxButtonPush> 

user002 update appwt ButtonPress>c : \acct\acct^M<ButtonPush> 

user003 accounts appwt nPressxLef tButtonPress>c : \acct\acct A M 

user004 customer type <Lef tButtonPressxLef tButtonPress>c : \ 



CurrentWindow 

Employee Records 
Acct Application 
Accounting 
Run 



=1 2.4.7 Global Variables 

ffi 

Q The Global Variables tool EMPOWER/GV, provides advanced control over multi- 

w user emulations by creating and controlling global variables that are shared among 

executing scripts. Global variables can be defined to direct scripts to terminate 
gracefully when they run an indefinite process. They also may be used to 
synchronize the execution of multiple scripts. Elements of EMPOWER/GV include, 
various commands and functions that control access to variables; read, update, or 
test values of variables; and control shared memory segments. 
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3.0 Installation 

EMPOWER/CS was designed to operate in an environment in which the SUT can 
not distinguish between actual PC users and the UNIX script driver. The PC, UNIX 
script driver, and SUT must be connected along the same communication network. 
The EMPOWER/CS software does not affect communication between the user PC 
and the SUT as it captures their activity. 

Before a Capture session begins, the PC will run a licensing check with the UNIX 
driver to verify execution of Capture. If the PC can not communicate with the UNIX 
machine, you will not be able to execute Capture. The PC must also be linked to the 

S UNIX script driver so that it may drive the PC during script execution in Display 

ffi mode. 

SI If the PC can not communicate with both the UNIX driver and the SUT, then 

% EMPOWER/CS can not capture client/server activity. If the UNIX driver and the 

IS SUT can not communicate, then the UNIX driver can not execute a multi-user 

emulation. 

The Capture, Display, and Tools elements of EMPOWER/CS run on a Microsoft 
Windows PC and the remaining EMPOWER/CS software runs on the UNIX script 
driver. So that the PC can communicate with the UNIX script driver for the licensing 
check and for script execution in Display mode, the PC must have installed the 
dynamic link library winsock.dll Version 1.1. The PC application communicates 
with the database according to how you have set up your client/server 
environment Both the PC and the UNIX driver must have the appropriate database 
libraries installed to communicate with the database on the server. 

When a script is executed, the PC no longer is required because the UNIX driver 
replaces the PC user to interact with the SUT. However, if you choose to observe a 
script as it progresses, you can activate the "Display" option for the script to display 
captured user activity on the PC. 



EMPOWER/CS-Vl.0.1 



3-1 



Copyright PERFORMIX. Inc. 0 1995 



User's Guide— Script Development 



3.1 The EMPOWER/CS Environment 

The following equipment is required to capture user activity with EMPOWER/CS: 

□ One IBM-compatible PC with keyboard, mouse, and monitor running Microsoft 
Windows software, winsock.dll Version 1.1, database libraries that assist with 
communicating with the SUT, and the EMPOWER/CS components Capture, Display, 
and Tools 

□ The UNIX script driver machine with database libraries that provide comparable 
communication with the SUT and EMPOWER/CS software 

□ The database server 

□ One communications network connecting the PC, the UNIX script driver, and the 
database server 



3.2 Installing the User PC, the UNIX Script Driver, and the 

*J Database Server 

O 

of! You should follow the appropriate installation procedures described in the owner's 

O manuals for the user PC, the UNIX script driver, and the database server. 



3.3 Installing the EMPOWER/CS Software 

You must complete two installations to fully operate EMPOWER/CS. The 
EMPOWER/CS components (Capture, Display, and Tools) must be installed on the 
PC and the remaining EMPOWER/CS software must be installed on the UNIX script 
driver. 
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3.3.1 Installing EMPOWER/CS on the UNIX Script Driver 

The EMPOWER/CS software package is installed into four directories. The bin 
directory contains binary programs, the lib directory contains libraries of compiled 
functions, the h directory contains header files, and the install directory contains 
installation files. 

You will need at least 15 megabytes of free disk space on your UNIX script driver 
to install and run EMPOWER/CS. You also will need additional space to store scripts 
and log files. The UNIX script driver must run a version of the UNIX operating 
system, the appropriate database libraries, and a C language compiler. 

P 

d5 To install the software, follow these steps: 

Step 1: Create a directory for the EMPOWER/CS software. 

The simplest directory to create is /usr/empower. Some customer sites 
create a separate EMPOWER/CS account and install the software in the 
home directory of that account If you create an EMPOWER/CS 
account, we suggest you call it empower in the event PERFORMIX must 
access the account for future maintenance or upgrades. 

The remaining instructions are based on installing EMPOWER/CS in 
/usr/empower. 

Step 2- Log in as the user who will own the EMPOWER/CS software. 
(Note: This user typically is empower.) 

Step 3: Change to the directory where the software will be stored: 

$ cd /usr/empower 

Step 4: Insert the EMPOWER/CS distribution tape into a tape drive. You must 
either use the default tape drive or determine the /dev name of the 
tape drive you will use. 
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Step 5: Use the tar command to read in the tape. Some examples of tar 
commands are listed below: 

$ tar xov 

$ tar xovf /dev/rSA/qtapel 

Step 6: Change to the install directory and execute the eminstall 

command. You will be instructed to contact PERFORMIX and provide 
your machine identification code to obtain your installation password, 
for example: 

$ cd Install 
$ ./eminstall 

You will receive a message similar to the following: 



Please print the • . . /Install/machineid" file, note your 
name, fax number, and phone number, and fax it to 
Performix at 703-893-1939. 

We'll generate your installation password and fax it back 
as soon as possible. When you get your installation 
password, re-run eminstall. 

If you are unable to send a fax, please call Performix at 
703-448-6606. 



This message is stored in the machineid file which can be printed and 
faxed to PERFORMIX. You will be given a special password consisting 
of all alphabetical characters, for example, jklmnopqrs- 

ABCDEFGHLMNOPWXYZ. 
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Execute eminstall again and enter the installation password when 
prompted. The interaction should look similar to the following example: 



$ . /eminstall 


Installation 


password: JKLMNOPQRS-ABCDEFGHLMNOPWXYZ 


installing . . 


/lib/empowercs . a . . . 


installing . . 


/ lib/ empower csm . a . . . 


installing . . 


/bin/cscc . . . 


installing . . 


/bin/draw. . . 


installing . . 


/bin/extract. . . 


installing . . 


/bin/gv_cmds . . . 


installing . . 


/bin/mix. . . 


installing . . 


/bin/mon. . . 


installing . . 


/bin/report. . . 



"4J Step 7: If your system supports ranlib ( 1 ) (usually on BSD versions of UNIX), 

cl run ranlib against the EMPOWER/CS function libraries: 

-J3 $ ranlib lib/*, a 

The software installation is now complete for your UNIX script driver. You must 
p now proceed to the next section to configure the UNIX script driver for 

fy EMPOWER/CS. 



3.3.2 Configuring the UNIX Driver for EMPOWER/CS 

Step 1: Log in to your system as the user who will use EMPOWER/CS. (/Vote- 
Running EMPOWER/CS or any other software package as root is not 
advisable.) 

Step 2: Define your shell environment variable empower to be the directory in 
which EMPOWER/CS was installed. 



EMPOWER/CS-Vl.0.1 



3-5 



Copyright PERFORMIX. Inc. © 1995 



User's Guide— Script Development 



For example, if you are a C-shell user, add the following line to the 
.cshrc file in your home directory: 

setenv EMPOWER / us r/ empower 

If you are a Bourne-shell user, add the following line to the .profile 
file in your home directory: 

EMPOWER=/usr/empower; export EMPOWER 

Add $ empower/ bin to your path. This step is accomplished by 
modifying the path statement in the .cshrc or .profile file in your 
home directory. You must modify your path to be below the setting of 
the empower environment variable. 

If you are a C-shell user, the path setting statement in your . cshrc file 
should be: 

set path = ( . /bin /usr/bin $ EMPOWER /bin ) 

If you are a Bourne-shell user, the path setting statement in your 
.profile file should be: 

PATH=. : /bin: /usr/bin : $EMPOWER/bin 

Step 4: Log out of your system and then log back in. This step causes your 
environment variables and path to be set correctly. 



3.3.3 Installing EMPOWER/CS on the PC 

When you install the EMPOWER/CS components onto your PC, EMPOWER/CS 
libraries and directories are created automatically. By default, the EMPOWER/CS 
libraries are placed under the directory empower which also includes a bin 
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directory of binary programs. If you wish to place these files under a directory 
other than empower, specify a new directory during installation when prompted. 

You will need at least five megabytes of free disk space on your PC to install and 
run EMPOWER/CS. You also will need additional space to store scripts and log 
files. The PC must include the libraries of the database server, the DOS operating 
system, and Version 3.1 of Microsoft Windows. 

To install the EMPOWER/CS components onto your PC, follow these steps: 

Step 1: Insert the Installation diskette into your disk drive. 

Q Step 2: From the DOS prompt, switch to the appropriate disk drive. Execute the 

'5 DOS install command from the correct disk drive by typing the name of 

the drive and csinstal (Example: a : \csinstal). If Microsoft 
Windows is already running, in the Program Manager window, choose 
Run from the File Menu. In this window, type the name of the drive and 
^ the install command (Example: a:\csinstal) and select OK. 

y. Steip 3: Follow the instructions that appear on screen for the remainder of the 

Q installation. 



Li i 



3.4 Before Starting Capture 

Before you can Capture with the EMPOWER/CS software, a licensing verification 
must occur between the PC and the UNIX script driver. This licensing check will 
occur when you start Capture. 

Before starting Capture, you must run eld on the UNIX machine. You should start 
eld as super-user (root) and you must set and export the empower environment 
variable to the local directory that contains the EMPOWER/CS software. 
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Example: 

# EMPOWER= /us r / empower 

# export EMPOWER 

# eld 



You now should be able to use the EMPOWER/CS software. Confirm the 
installation by starting Microsoft Windows on your PC and activating the 
EMPOWER/CS window and then the Capture icon. 

The software installation and setup are now complete. Remove the EMPOWER/CS 
tape from the tape drive and store it, with the EMPOWER/CS diskette, in a secure 
location. 
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4.0 Capture 

The EMPOWER/CS Capture tool is used to capture communications between a 
user PC and the SUT to build executable scripts. After you complete a Capture 
session, the assembled scripts can be executed from a UNIX script driver to 
emulate numerous users of the client/server system. 

When activated, Capture records all interactions between the PC and SUT including 
mouse and keyboard strokes, SQL requests to the SUT, and data transmitted to the 
PC. Automatically, this information is stored in a script file with a \c" extension in a 
specified directory on your PC to be used for subsequent script execution. The . c 
extension implies that the file is recorded in C language syntax for later C 
compilation and execution. Refer to Sections 5 and 6 of this manual for more 
information on script compilation and execution. 

The following script segment illustrates the types of user functions and database 
traffic contained in a script This script contains such captured activity as user 
entries, connection and logging on to the database, and execution of a query: 

AppWait(0.22) ; 

WindowRcv ( "SfAcSfDwDwAcSf Sf Sf PtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPt" ) ; 
WindowRcv ( " PtPtPtPtPtPtPtPtPtPt " ) ; 

CurrentWindow(" Program Manager" , 36, 26, 545, 333) ; 

SysKeyPress (VK_MENU) ; 

Type(-fr-) ; 

AppWait(0.06) ; 

WindowRcv ( "CoCwCwCwCwCwCvA^wCwSCAcPt" ) ; 

CurrentWindow( "Run* ,72,77,450,238) ; 

Type ( - c : \ \acct\ \acct"M- ) ; 
WindowRcv ( " CwCwCwCwCwCwCw " ) ; 

Openenv { ORACLE , VERS IONV6V7 ) ; 

( continued on following page . . .) 
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Username(LOGl, "scott/tiger@SUT" ) ; 
Password ( LOG1 , • " ) ; 
Logon ( ORACLE , LOG1 ) ; 

WindowRcv( "SfAcSf SfSfDwPt" ) ; 

CurrentWindowC Program Manager" , 36, 26, 545 , 333) ; 
Open (LOG1 , CURl ) ; 



AppWait(4.84) ; 
WindowRcv( "AcSf Pt" ) ; 

CurrentWindow ( "Accounts ",147,66,533,360); 
ButtonPush ( " Payable - , 267 , 213 ) ; 



AppWait(0.05) ; 

WindowRcv ( " Sf PtCv^<^*X><^X^X^X^^ ) ; 

Begin timer ( " Account s_Payable " ) ; 
Dbset (CURl, DEFER, TRUE) ; 

Parse (CURl, - SELECT ID, FIRST_NAME, LAST_NAME, ADDRESS_LINE_1 , ADDRESS_LINE_2 . 
ADDRESS_LINE_3 , PHONE_NUMBER , FAX_NUMBER , COMM_PAID_YTD, ACCOUNT_BALANCE , COMMENTS 
FROM CUSTOMERS ■ ) ; 

DescribeAlKCURl, 1, 12); 

Dbset (CURl, MAXARRSI2E, 64) ; 



Define (CURl, 


"1", 


STRING, 40) ; 


Define (CURl, 


"2-, 


CHAR, 


21) 




Def ine(CURl, 


"3\ 


CHAR, 


21) 




Define (CURl, 


-4", 


CHAR, 


21) 




Def ine (CURl, 


"5", 


CHAR, 


21) 




Def ine (CURl, 


"6-, 


CHAR, 


21) 




Define (CURl, 


■7-, 


CHAR, 


16) 




Def ine (CURl, 


M 8-, 


CHAR, 


16) 




Def ine (CURl, 


"9", 


STRING, 40); 



Define(CURl, "10", STRING, 40); 
Define(CURl, "11", CHAR, 241); 
Exec (CURl) ; 

Dbset (CURl, FETCHSIZE, 64); 
Fetch (CURl) ; 

while (GetNextRow(CURl) ! =NOMOREROWS) ; 
Endtimer( "Account s_Payable) ; 
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For a more detailed explanation of script content, please refer to Section 7 Script 
Content and Enhancement of this manual. 



4.1 Suggestions for Executing Capture 

If you plan to execute EMPOWER/CS scripts in Display mode, you must ensure 
that the steps captured in the application to be tested are repeatable, meaning that 
all captured mouse activity can be precisely repeated by the UNIX script driver 
machine during script execution. Capturing mouse clicks in each activated window 
is not recommended because the recorded mouse locations, i.e., xy coordinates on 
screen, may not apply during script execution. For instance, windows do not always 
open in the same location each time they are activated. During script execution in 
Display mode, the recorded xy coordinates in the mouse event functions could be 
invalid and cause the script to malfunction by not activating the correct locations to 
activate applications or commands. Maximizing windows will ensure that all mouse 
actions are repeatable because the window will cover the entire screen allowing 
recorded xy coordinates to remain the same in Display mode. 

Since keyboard presses and commands are more precise, we recommend that you 
use the keyboard as much as possible to activate windows, commands, or 
applications. Some keyboard capabilities are listed below: 

O Alt + Space Bar to open system menus 

O Alt + F to open file menus 

O Control + F4 to close program windows 

O Arrow keys to move through menus or among icons 

Refer to your MS Windows user guide for full instructions on using the keyboard 
to control your Windows desktop. 
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4.2 Executing Capture 

Capture is executed from Microsoft Windows on your PC 

If Windows is not currently running on your PC, from the DOS prompt, type "win" 
and press return. 

The Windows desktop and Program Manager window will open containing various 
program group icons. Activate the EMPOWER/CS program group. 

Example: 



Program Manager 



File Options Window Help 



£ 51 -A 

AVO 




a 45 

AVO 




£51=* 

A V © 




AVO 




£ 51 =A 

AVO 











Applications StartUp 



PC/TCP 
DosApps 



Empower/OS 



Main 



a « ;5 

A £ o 




a «! _* 
^ £ o 




e « _4 
4£ o 




fl4i 

4 £ © 




a « ^ 



Accessories 



Games 



Microsoft 



PC/TCP 

\ . /:.. a 



wIN STALL 3.3 
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The following EMPOWER/CS window will open which includes three program-item 
icons: Capture, Display, and Tools. 

Select the Capture icon: 



Program Manager 



File Options Window Help 



a « .i 






4£® 







StartUp 



PC 
Dc 



£ £ =* 









Accessories 



Empower/CS 



Capture 



Display Tools 



Before you may begin Capture, the PC must set up an initial communication or 
licensing check with the UNIX script driver. If this initial contact can not be made, 
you will not be able to execute Capture and will receive sn error. Note: You must 
be sure to run eld as root on the UNIX machine before starting Capture on the PC 
(Refer to Section 333 of this manual). 



If the licensing check was successful, the following Capture command window will 
open prompting you to enter a script name: 
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This Capture window includes two items in the Menu Ban File and Help. The File 
menu, includes Options..., Directory..., and Exit The Help Menu (located in all the 
EMPOWER/CS windows) includes About... for listing EMPOWER/CS copyright 
information. 

The About Capture screen is shown below: 



Capture 

Empower/CS Capture v1.0 
© Performix, Inc. 1994 
Serial ff. ROOOOO-000 



[OK] 



Before you enter a script name to begin capturing, you may wish to change some 
of the Capture menu options. Under the File Menu, select Options.... 
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4.2A Options 

When you choose Options..., the following Options window will open: 



Capture Options 



Think Threshold 



Bring to front with F12 



View script D 
Transfer script after capture I 



Host 
Username 

Password 



indy 



john 



******** 



Remote Directory ftemp 



□ Database traffic only 

□ Insert timers 



Database. 



License Daemon 



foo 



OK 



Cancel 



These Options are described more fully in subsequent sections. 
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When you change an option and select OK, a verification window will appear asking 
you to confirm changes. 

Example: 




If you select OK again, another Window will appear stating that the Options have' 
been saved. Select OK to return to the Capture command window. 



a 



Capture 



Options saved 



OKI 
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To ignore any changes you made, select Cancel. A verification window will appear 
stating that the changes will be lost Select OK to return to the Capture command 



In the Options window, you may change any of the Capture options during your 
Capture session, except Database traffic only and the Database . . . Chooser. 



This option specifies the number of seconds that EMPOWER/CS will wait before 
inserting a Think () function into the script .c file. (Refer to Section 7 Script 
Content and Enhancement for a more detailed explanation of think time functions.) 
For example, suppose you specify a Think threshold of 2 seconds. If no activity is 
captured after two seconds, EMPOWER/CS will insert a think time function of at 
least two seconds and the time elapsed until the next action occurs. 

You may specify any two digit number of seconds for this option. 



window. 



Example: 





4.2.1.1 Think Threshold 
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4.2.1.2 Bring to Front with 

Once you have begun capturing activity, the Capture window will minimize into the 
lower left corner of the Windows desktop. (Note: If you have maximized the 
window of your test application, you will not be able to see the Capture icon.) By 
simply pressing a hot key, you can bring the Capture command window up, 
temporarily halting the session. 

With this option, you may specify one of the function keys (Fl, F2, etc.) as a hot 
key. The default hot key is F12. 

Example: 



Capture Options 



1 ^ 


Think Threshold 


0 






Bring to front with 


F12 


± 






F10 


t 


ry 


View script 


F11 




3 3 

hop 


[-Transfer script after ca 


F12 





Host 



indy 



□ Database traffic only 

□ Insert timers 



Database... 



Note: You should specify a function key that will not be used in your application. 



4.2.1.3 View Script 

Selecting the View script option allows you to look at the script file as you Capture. 
During Capture, the View script window appears on screen showing the script .c 
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file as user and database activity is captured. This option will help to familiarize you 
with the script functions that relate to activity you capture. 

The following example demonstrates a View script window during Capture: 



lew lex 



Dberror(CONTINUE); 
Unset(NOTIFY); 

Beginscenariofexl"); 



r What to do on Database errors */ 
r Don't display warnings. I'll use Mon to find them */ 



IT 



4.2.1.4 Database Traffic Only 

If you select this option, only database traffic will be captured into the script, which 
makes your script more compact 



Database traffic includes such functions as Open!), Parsed, (),Exec(), 
Fetch { ), etc which are inserted into the script when the client application interacts 
with the database. Mo user interactions, such as mouse button presses or Type { ) 
functions, are inserted into the script file. However, the amount of time taken to 
type characters or move the mouse will be included in the Think ( ) times that are 
recorded into the script. (Refer to Section 7 Script Content and Enhancement for a 
full description of these script functions.) 



If you specify this option, your script can be executed only in Non-Display mode. 



4,2.1.5 Insert Timer 

If you specify this option, Begintimer ( ) and EndtimerO functions are inserted 
automatically into the script during Capture to mark database traffic. These 
functions will be inserted around database traffic that occurs between two user 
events. A user event such as pressing the Return key on the keyboard or 
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activating a pushbutton on screen may initiate database activity. The parameters to 
these functions will designate the last user event before database activity began. 

When the script is exectued, the Begintimer ( ) and Endtimer ( ) functions will be 
time stamped in the scripts log file for the Report tool to measure response time of 
the database activity. 

The following example demonstrates Begintimer { ) and Endtimer () captured 
into a script file around a database query. Notice the user event captured as the 
functions' parameters was a ButtonPush{ ) event, when a user pressed the button 

"Payable": 



Cur r en tWindow( "Accounts" , 147 , 66, 533, 360) ; 
ButtonPush( "Payable" ,267,213) ; 

AppWait (0.05) ; 

WindowRcv ( " S f P tCwCwG wCwCwCwCwCwCwCwCwCwCw " ) ; 

Begintimer ( n Accounts Payable M ) ; 

Dbse t { CUR1 DEFER , TRUE ) ; 

Parse (CUR1, " SELECT ID, FIRST_NAME, LAST_NAME, ADDRESS_LINE_1 , 
ADDRESS_LINE_2 , ADDRESS„LINE_3 , PHONEJSTUMBER , FAX_NUMBER, COMM_PAID_YTD, 
ACCOUNT_BALANCE, COMMENTS FROM CUSTOMERS "); 

DescribeAll (CUR1, 1, 12); 



Endtimer { " Accounts_Payable" ) 



4.2.1.6 Database Chooser 

This option allows you to choose the database on the server that you will access 
during the Capture session. 
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A window similar to the following opens when you select this option: 




4.2J.7 Transfer Script after Capture 

Once a script is captured, it must be transferred to the UNIX machine to be 
executed. If you select this option, your script .c file will be transferred automatically 
when you stop Capture. 

You must specify the following information for the PC to connect to the UNIX script 
driver and transfer the script file. 
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Example: 



-Transfer script after capture 



Host 
Username 

Password 



foo 



john 



A A A AAA 



Remote Directory /tmp| 



License Daemon 



indy 



OK 



Cancel 



In the Options window, enter the Host name (the name of the UNIX driver), the 
Username, the Password (the user's password, if any), and the Remote Directory 
(the path on the UNIX driver where you wish to transfer the script). 

If large amounts of data (i.e., images, large text files, etc.) are input to the database 
during Capture, such data is inserted into separate data files. These data files will be 
transferred to the UNIX driver machine with the script if the Transfer script after 
capture option is selected. The data files are associated to the script with a . d 
extension' and a number that is incremented for each file. For example, two data 
files created for the script, scriptl .c, would be named as follows: 



scriptl.dOl 
scriptl .d02 

If you prefer, you may transfer the script file manually with the Transfer tool under 
EMPOWER/CS Tools. Refer to Section 8 EMPOWER/CS Tools for more 
information on manual script transfer. 
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4.2.1.8 License Daemon 

If you specified a license daemon during EMPOWER/CS installation, this option 
lists the name of that license daemon. If you need to change or specify a license 
daemon machine (which is the UNIX script driver used for your emulation), you 
must enter the new name in this dialog box. 



4.2.2 Directory 

You may use this File Menu option to store scripts in a different directory on your 
PC 

Select Directory... under the File Menu. The following window will open 
designating the directory and disk drive where your scripts currently are being 
saved. 
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Directory 



Directories: 
c:\ 



CD arcade 
C3 brriDS 
CD dash 
C] dcaD 
CD demo 
CD dos 
C] emDower 
CD fltsim5 
Q ns 



OK 



Cancel 



Network. 



Drives: 



c: 



Select from the Directory list the name of the directory or the disk drive to which 
you wish to change, and then select OK or Cancel as appropriate. 



4.2.3 Capturing Application Activity into a Script File 

In the Capture command window, enter the script name you are capturing. The 
script file name can include up to eight alphanumeric and underscore characters. If 
you enter more than eight characters or other character types, Capture will ignore 
them. During Capture, the script file is stored automatically in the specified 
directory in an ASCII file with a ".c" extension. 
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Example: 



ffi 




When you have entered a script name, select Start 

If the script name you enter already exists, the following warning message will 
appear, asking if you wish to overwrite the existing file. Select OK or Cancel as 
appropriate. 



0 



Warning 



Script 'examplel .c* exists, overwrite? 





OK! 




Cancel 



Upon selecting Start, the Capture window will minimize, or iconify, into the lower 
left comer of the desktop signifying that all subsequent user and database actions 
are being captured 

Now, you should open the application to be tested Refer to your application's user 
guide for full operating instructions. Remember to maximize your application 
window upon activation if possible and use keyboard commands instead of the 
mouse during your Capture session. 
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Please note that user activities are captured only from Windows standard 
applications. For example, EMPOWER/CS does not capture user activity from DOS 
applications running under Windows. 

At this time, you should perform the application activity you wish to test 



4.2,4 Comments, Functions, and Timers 



~*4 



You can add timers functions, or comments, to your script file while you are 
capturing by activating the Capture icon. The following Capture command window 
will open. When the Capture window appears on -screen, all capturing activity halts 
temporarily. 



file Help 



Timer 
Function 
Comment 



Capture 



Begin 



Begin 



Insert 



Resume 



Stop 



Inserting timers allows you to mark specific activity for response time 
measurement. C language functions most commonly are used to help define a 
script segment for looping purposes. They also are used to define a common 
interaction, such as logging onto or off of the SUT. You should add comments to 
your script file to add context to the script for editing purposes. 
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4.2.4.1 Inserting Timers 



You can manually insert the functions Begintimer { ) and Endtimer ( ) into your 
script to mark activity for response time measurement You must enter the name of 
the timer in the Timer dialog box of the Capture window and select Begin. . Select 
the Resume button to return to the Capture state to capture the activity you wish to 
measure. 

When you have captured all needed activity, activate the Capture icon to open the 
Capture window. Select the End button next to the Timer dialog box. The following 
window will appear to verify the end of the timer 




If you have finished inserting the timer, choose OK in this verification window. 
Your desktop then will return to the Capture state. 



4.2.4.2 Inserting Functions 

To create a C function, enter the name of the function in the Function dialog box 
and select Begin. Select the Resume button to return to the Capture state to capture 
the function activity. 

After you have completed capturing the function, activate the Capture window and 
select the End pushbutton next to the Function dialog box. 
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The following window will appear verifying the end of the function: 





Function 






End function "query!" 


1 [OKj 


Cancel 













If you have finished inserting the function, choose OK in this verification window. 
Your desktop then will return to the Capture state. 

When you create a function, a function call is inserted within the script and the 
actual function (that includes captured activity) is placed at the end of the script file. 
Automatically, the EMPOWER/CS functions Beginf unction ( ) and 
Endf unction ( ) are inserted around the captured function. After a script is 
executed, Beginf unction ( ) and Endf unction ( ) cause time stamps to be 
recorded in a log file which is used to create detailed response time reports. 
Marking functions in such a way allows you to measure reponse time for specific 
activities in your application. Refer to Section 6.4 The Log File in this manual and to 
Section 3.3 of theMulth User Testing manual for more information on time stamps. 

The following example demonstrates a function logout ( ) that was captured into 
the script file, scriptl.c: 
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logout ( ) 
{ 

Beginsource ( M scriptl . c u ) ; 
Beginf unction ( " logout " ) ; 

Think (4. 66) ; 

Lef tButtonPress (202, 99) ; 

Lef tButtonPress (236, 244) ; 

AppWait (0.28) ; 
WindowRcv ( M ScDwAc " ) ; 

CurrentWindow( "Capture - scriptl " , 21 , 690 , 57 , 726 ) ; 
Commit (LOG1) ; 

WindowRcv ( M Pt") ; 
Logoff (L0G1) ; 
Closenv (ORACLE) ; 

Endf unction ( M logout " ) ; 

Endsource( ) ; 

} 

1 : ■ _J 

Beginsource ( ) and Endsource ( ) statements are automatically inserted around 
BeginfunctionO and Endf unction ( ) to prepare the function as a source file. 
For instance, during a multi-user emulation, you may wish to break the function out 
of the script into its own separate file that could be called by multiple scripts 
performing the same function. Modular script design is achieved by storing one or 
more functions in separate script source files. The C language cc compiler allows 
functions stored in these files to be compiled separately and then linked to the 
primary script file. Beginsource ( ) and Endsource ( ) specify the source file used 
during script execution. 
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EMPOWER/CS organizes functions as described in this section to format the script 
as a C language program. Refer to Section 5.23 Modular Script Design for a more 
detailed description of C function formatting. 



4.2.4.3 Comments 

You may insert a C comment into your script by entering the comment in the 
Comment dialog box of the Capture window and selecting Insert 



Select the Resume or Stop pushbutton as appropriate when you have entered your 
comment If you select Resume, your desktop will return to the Capture state. 



4.2.5 Completing Your Capture Session 

After you complete the application activity to be tested, close the application. 

Activate the Capture icon to halt the Capture session. The Capture window will 
appear. 



If you are ready to end the Capture session, select the Stop, button or Exit from the 
File menu. The following window will appear verifying that Capture has stopped: 
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If you did not connect to the SUT to capture database traffic during your Capture 
session, the following warning message will appear as soon as you stop Capture. 



Warning 



No database traffic captured 



lOKj 



If you chose the automatic transfer option, your script will transfer automatically to 
the UNIX script driver after OK is selected in the Capture Stopped window. A 
window similar to the following appears that shows the progress of the file transfer 



Transfer 



Attempting to connect to "indy" 



0% 

Cancel 
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If the PC is unable to connect to the UNIX driver, a message window similar to the 
following will appear 



Transfer 



Unable to connect to 'too' 



0% 

iokT 



If the script .c file already exists on the UNIX script driver upon a successful 
transfer, the following window will come up asking you to overwrite the existing 
script .c file. Choose OK or Cancel as appropriate: 



Warning 



(J) Script "exl c' exists on 'indy', overwrite? 





OK 






Cancel 



If you did not select the automatic transfer option, you may transfer the script 
manually using the EMPOWER/CS Transfer Tool (see Section 8.0 EMPOWER/CS 
Tools) or a third party File Transfer Protocol (FTP) software. 



The Capture session is now complete. At this point, you can begin to capture 
another script or you can close Capture by selecting "Exit" from the File Menu. 
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If you choose Exit, you now are ready to compile your script(s) with Cscc on the 
UNIX script driver. Cscc is the EMPOWER/CS tool that compiles your scripts into 
machine language binaries for execution. If you wish to edit your script .c file, you 
should do so with a system editor such as vi after the script file has been 
transferred to the UNIX script driver. Refer to Section 7.0 Script Content and 
Enhancement for information on editing your scripts. 
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5.0 Cscc 

The EMPOWER/CS tool, Cscc f reads and compiles script files, translating them into 
machine language form. After compilation, the script can be executed from the 
UNIX driver machine for multi-user testing eliminating the need for multiple PCs. 
Script execution is accomplished in two steps: The script first must be compiled 
and then the compiled script is executed. This approach allows C language 
statements to be embedded in the script file to enhance control over script 
execution. 



5.1 Cscc Syntax 

Script compilation with Cscc begins with the cscc command. The syntax of the 
cscc command is given in the following usage message which you can access by 
entering cscc with a hyphen (-) parameter. 

$ cscc - 



EMPOWER/CS VI. 0.1, Serial #R00OO0-000 , Copyright PERFORMIX, Inc. 1988-95 
Usage: 

cscc [-EFOacghsvm] [ -o ofile] script ... 

Options: 

-E Preprocesses the script and writes C to stdout 

-F Inserts function declaration (implies -c option) 

-O Optimize script binary 

-a afile Create an archive (.a file) from the named files 

-c Compile but do not link (creates .o file) 

-9 Includes symbol table in script binary for debuggers 

-h Excludes help information from the script binary 

-s Prevents strip of script binary 

-v Print verbose cc command line 

-m Excludes Monitor code from script binary 

-o ofile Name output binary 



Notes : 



Before running CSCC, set the environment variable EMPOWER to the 
directory that contains the EMPOWER software. 
Set the environment variable E_C FLAGS to any additional cc 
compile options you want. 
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5.2 Cscc Environment Variables 

Cscc uses several environment variables. The EMPOWER/CS variable must be set 
to the name of the directory containing the EMPOWER/CS software before you 
can execute Cscc. 

Example: 

$ setenv EMPOWER /usr/ empower 

The EMPOWER/CS directory contains four sub-directories: bin, lib, h, and 
install. Cscc will search the lib and h directories for files needed during script 
compilation. If you have not set the EMPOWER/CS variable, Cscc will search the 
current directory for the files it needs *nd produce an error message similar to the 
following: 

can't find empowerm.h 

Cscc permits you to use a temporary directory other than the current directory for 
C compilations. Set e_tmpdir equal to the name of the temporary directory. 

Example: 

$ setenv E_TMPDIR n /tmp n 

Also before you can execute Cscc, certain environment variables must be set to 
specify the databases being used. The environment variable e_databases must be 
set to designate which database with which you are going to compile. Valid choices 
for Oracle and Sybase databases are 0RACLE7, sybase4, or.SYBASElO. Note: If you 
are not sure which version of Sybase was used during Capture, you can look in 
your .c file for the Openenvl) function. The second parameter will list the 
appropriate version. 
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If necessary, this environment variable can be set to more than one database. 
However, you should only specify the database(s) you used during the Capture 
session. 

Example: 

$ setenv E_D ATAB AS E S ORACLE 7 

With each e__databases environment variable you must set the Oracle or Sybase 
environment variables. 

If compiling with an Oracle database, set the environment variable oracle_home to 
the path where Oracle resides on the server. 

Example: 

$ setenv ORACLE_HOME /uar/oracle 

If compiling with a Sybase database, set the Sybase environment variable to the 
appropriate path. 

Example: 

$ setenv SYBASE /usr/ Sybase 

You also can pass flags when invoking the C compiler by defining an environment 
variable e_cflags and setting the variable equal to your compilation flags. The 
flags will be inserted after the cc command and before the file name. 

If you require additional libraries during the load phase of the C compilation, define 
the e_libs environment variable equal to the names of the libraries. 

Example: 

$ setenv E_LIBS "-la" 
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5.3 Compiling with Cscc 

To compile a script, you must enter the cscc command with the name of the 
source script. (Note: You do not need to specify \c" in the script file name 
because Cscc automatically searches for a file with this extension.) 

Example: 



$ cscc exaznplel 

Cscc: EMPOWER/CS VI . 0 . 1 , Serial #ROOOOO-000 , Copyright PERFORMIX, Inc. 



1988-95 

cc -s -o examplel ./cscc7086.c /usr/local/lib/* . a 



Cscc will look for the specified script file in the current directory. If you have saved 
the script file in a different directory, you can specify the path of the directory as 
part of the file name specification. 



$ cscc /usr/empower/scripts/examplel 

During script compilation with Cscc, the source script is converted and placed in a 
temporary file in the current directory. Then, the C compiler is invoked to compile 
this temporary file. During the load phase of compilation, a special library of 
EMPOWER/CS functions is included. Once the compilation is complete and the 
executable file has been created, the temporary file is removed automatically and 
the executable file remains in the current directory. 



Cscc creates an executable file called examplel (with no extension) which can be 
executed by typing this file name at the command line. 



5.3.1 Specifying the Binary Name with -o 

By default, Cscc creates a binary version of the script with the same name as the 
script file but without the .c extension. If you want to save the binary with a 
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different name, you can use the -o option of the cscc command to specify the 
desired name. 

In the following example, the created executable script will be named databasel 
instead of query. c: 



$ cscc -o databasel query, c 



5.3.2 Preprocessing the Source Script with -E 

Before a script can be executed as a C language program, it must be preprocessed 
to include C function formatting (e.g., braces, functions, etc.) in the source script file. 
By default, the cscc command automatically preprocesses the source script file. 
Also, if you capture functions during your Capture session, this C function 
formatting is inserted into the script file automatically. 

If you choose only to preprocess the script file without compiling it, you should use 
the -E option of the cscc command. Entering the -E option of the cscc command 
will convert and write the script source file to the standard output You can display 
this converted file on screen for review or save it to a C program file for editing 
and later compilation. 



When Cscc is invoked on a preprocessed file, the main() C function will indicate 
to Cscc that no preprocessing is necessary. When Cscc compiles such a file, the 
library of EMPOWER/CS functions will be included. 

The following example shows preprocessing of the script source file examplel .c: 
$ cscc -E examplel 

If you prefer to save the converted file to a C program file, specify the name of the 
new file as part of the cscc command, as follows: 
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$ cscc -E examplel>newscript . c 
The file newscript.c can then be compiled with Cscc: 



$ cscc newscript 

Cscc: EMPOWER/CS VI . 0 . 1 , Serial #ROO00 0- 000 , Copyright PERFORMIX Inc 
1988-95 

cc -s -o newscript newscript.c /usr/local/lib/ * . a 



5.3.3 Modular Script Design 



Since EMPOWER/CS scripts are C language programs, defining a common 
interaction in a C language function often is useful. This allows a script to include a 
function call rather than the complete set of script entries for activities that you 
want to be repeated within the script. For example, the following script starts with 
the EmpowerCSO function. The EmpowerCSO function is similar to main() in a 
normal C language program. This function calls the function, f unctionl ( ) , which 
is located later in the script 



EmpowerCS { argc , argv) 
int argc; 
char * * argv; 



{ 



Thinkuni form { 1 , 2.5); 
Timeout (300, EXIT) ; 
Unset (NOTIFY) ; 

Beginscenario ( M script 1 " ) ; 

InitialWindow<0, "Desktop" , 0,0, 1024, 7 68) ; 
InitialWindow(l, "Program Manager" , 830, 186, 73 , 605) ; 
InitialWindow(2 , "Accounting" , 413 , 679 , 1029 , 771 ) ; 



AppWait (0.06) ; 
WindowRcv ( "CwPtPt " ) ; 



( continued on following page . . .) 
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LeftButtonPress(457, 617) ; 

WindowRcv( " DwCoSf CwCwCwCwCwCwCwCwCwCwSf AcSzPt " ) ; 
CurrentWindow("Run M , 429, 491, 880, 764) ; 
Type( :c:\\acct\\acct A M n ) ; 

f unctionl ( ) ; 



CurrentWindow( "Capture - scriptl " , 21 ( 690 , 57 , 72 6 , "Min" ) ; 
Commit (LOG1) 

Close (CUR1) ; 



WindowRcv ( " Pt " ) ; 

Logoff (LOG1) ; 

C 1 os env (ORACLE) ; 



Endscenario ( " scriptl " ) ; 



} 



functionl ( ) 
{ 



Beginsource { M scriptl " ) ; 
Beginfunction( "functionl" ) ; 

AppWait (0.22) ; 

WindowRcv ( " CwCwCwCwCwCwCwCw " ) ; 
Openenv (ORACLE, VERSIONV6V7) ; 

Username(LOGl, " scott/ tigerQSUT" ) ; 
Password (LOG1, " " ) ; 
Logon (ORACLE, LOG1) ; 

Open ( LOG1 , CUR1 ) ; 

WindowRcv ( "AcS f ) ; 

CurrentWindow ( "Accounting Application" , 189, 82 , 685, 449) ; 



Endfunction( " functionl") ; 
Ends our ce ( ) ; 
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IV2 



The function syntax can be inserted manually or may result from inserting a 
function during Capture. (See Section 42.4.2 Inserting Functions.) 

Your script also can access functions that are stored in other script files. Modular 
script design is achieved by storing one or more functions in separate script 
source files. The C language cc compiler allows functions stored in these files to be 
compiled separately and then linked. 

You must use the -c option of the cscc command to create object files (with an M .o" 
extension) for each compiled script 

Examples: 

$ cscc -c fund 
$ cscc -c £unc2 
$ cscc -c func3 

For a script to access these functions, a function call must be inserted within ihe 
script and the object files must be linked with the source script. This is 
accomplished by compiling the script source file and listing the object files as 
parameters of the cscc command, as shown below: 

$ cscc script 1 funcl.o func2.o func3.o 

In the above examples, three separate functions are stored in the script source files 
fund . c, f unc2 . c, and f unc3 . c. Each is compiled separately and then linked to 
the source script file, scriptl .c. 

Individual object files may be stored and used by other scripts or included in an 
EMPOWER/CS library. 

When the -c option of the cscc command is used, the function stored in a 
separate file must include standard C language function formatting (e.g., braces, 
functions, etc.). 
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If a script is compiled from multiple source files, each source file must be specified 
as a source file by including Beginsource ( ) and EndsourceO statements. When 
editing your script, you should insert the Beginsource ( ) function at the entry 
point of the source file, typically just before the first executable statement in each 
function. You should insert the EndsourceO function at the exit point of the file, 
typically just after the last executable statement in each function. 

The following example script segment demonstrates a typical source file: 



logonlO 
{ 

Beginsource { w logonl M ) ; 
AppWait (0.17) ; 

WindowRcv ( M Sf PtCwCwCwCwCwCwCw" ) ; 
Openenv ( ORACLE , VERS IONV6 V7 ) ; 

Username (L0G1 , "scott/ tigerQSUT" ) ; 
Password (L0G1, " M ) ; 
Logon ( ORACLE , L0G1 ) ; 

WindowRcv ( " Sf AcSf DwPtPtPtPtPtPt " ) ; 

CurrentWindow( "Accounting" , 413 , 679 , 1029 , 77 1 ) ; 

Open (LOG1, CUR1) ; 

WindowRcv ( "AcSf M ) ; 

CurrentWindow< "Accounting Application 1 * , 189 , 82 . 685, 449 ) ; 

Endsource ( ) ; 
} 



Note: If you define C functions during your Capture session, Beginsource ( ) and 
EndsourceO are placed around Beginf unction ( ) and Endf unction ( ) 
statements in the event you wish to break the function out later into a separate 
source file. 
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5.3.4 Extending Modular Script Compilation with -F 

The -f option of the cscc command extends the capabilities of modular script 
compilation to handle functions that do not include standard C function formatting. 
This option places the required formatting into the script automatically. 

For example, elements of the logonl ( ) function may be contained in the following 
script file called logonl . c: 



m 



Beginsource { " logonl " ) ; 
AppWait (0.17) ; 

WindowRcv ( " Sf PtCwCwCwCwCwCwCw" ) ; 
Openenv ( ORACLE, VERS I0NV6V7 ) ; 

Username(LOGl, " scott/ tiger@SUT" ) ; 
Password ( LOG1 , " " ) ; 
Logon (ORACLE , LOG1) ; 

WindowRcv ( " Sf AcSf DwPtPtPtPtPtPt " ) ; 

CurrentWindow( " Accounting" , 413 , 679 , 1029, 771) ; 

Open(LOGl,CURl) ; 

Endsource ( ) ; 



To compile this file into the object file logonl. o, use the -f option: 



$ cscc -F logonl 



Cscc adds the function definition logically to the source file and compiles it into the 
object file logonl .o. The -F option may not be used if the function is required to 
accept arguments. 
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5.3.5 Automatic Creation of Function Archives 

EMPOWER/CS can create archive and function libraries automatically with the -a 
option of cscc. This option is used as follows: 

$ cscc -a logonl funcl func2 

The -a option is followed by a list of script file names to be included in the archive. 
If a M . o" file exists for the given script file, the " . o" file also will be added to the 
archive. If a ".o" file does not exist, Cscc will search for a ".c" file with the 
provided name. If a ".c" file is found, it automatically will be compiled with the -c 
option , and the resulting ".o" file will be included in the archive. 

The name of the archive will be the first script name given, with a " . a" extension. 
The above example would create an archive file called logonl. a, which would 
include the files login . o, funcl . o, and f unc2 . o. 

The e_libs environment variable must then be set to include the archive file. 
Future execution of Cscc will include the new archive. Set the e__libs environment 
variable as follows: 

For Bourne shell users: 

$ E_LIBS=logonl.a; export E_LIBS 

For C Shell users: 

$ setenv E_LIBS logonl. a 

When the script is compiled with Cscc, the archive will be included in the compiler 
command line. 
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5.3.6 Optimizing and Stripping the Script Binary 

Cscc invokes the standard C language compiler "cc". By default, Cscc strips (does 
not include) the symbol table from the binary and does not optimize the binary. You 
can change these defaults with the -o f -s, and -g options of the cscc command. 

The -o option of cscc specifies that the resulting script object code is optimized. 
However, since a script is primarily a series of function calls that can not be 
optimized, the -o option has little effect and slows Cscc operation. 

Stripping the symbol table for a script makes it smaller; therefore, executing it 
requires less memory. However, you can specify that the symbol table is not 
stripped (is included) in the binary by using the -s option of cscc which invokes 
the -s option of the "cc" compiler. 

If problems occur during script execution, you may want to run a system debugger, 
such as dbx. System debuggers require that the symbol table is included in the 
executable script and that the file is not optimized. The -g option of the cscc 
command invokes the C compilers -g option to include the symbol table and 
prevent optimization. This option, described in the manual for the cc compiler, will 
allow the resulting executable file to be used in a system debugger. 

An executable script file created with the -g option will be rather large and will 
require a large amount of memory to execute. Therefore, using -g is not 
recommended for scripts executed during a sizable multi-user emulation. 



5.3.7 Excluding Help Information from the Script Binary 

By default, Cscc includes help information in the executable version of the script it 
creates. This help information is shown in the Syntax help screen in Section 6.1. 
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By using the -h option of the cscc command, you may compile the script to 
exclude help information from the executable file: 

$ cscc -h exaxnple30 

The resulting executable script will be smaller and require a bit less memory to 
execute. 

If you try to display help information for a script that was compiled with the -h 
option, the following error message will result: 



$ example3 0 

error: example30: no help available. recompile without the -h option. 



& 5.3.8 Excluding Monitor Code 

: , By default, Monitor code is included in the executable script file after it has been 

p compiled with Cscc. An executable script file with Monitor code is somewhat larger 

fy requiring more resources to run than a file without the code. 

s i * 

^ If you want to compile your script without Monitor code and therefore not use the 

^ Monitor tool, enter the -m option of the cscc command as demonstrated below: 

$ cscc -m example7 



5.3.9 The Compiler Command Line 

The -v option of the cscc command specifies that the entire compiler command 
be listed after a script is compiled. By default, EMPOWER/CS lists a condensed 
version of the compiler command that does not include all libraries and options. 
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An example of a default compilation follows: 



$ cscc scriptl 

EMPOWER/CS VI. 0.1, Serial#RO0000-000 , Copyright PERFORMIX, Inc. 
1988-95 

cc -s -o scriptl ./csccl7366.c /usr/local/lib/ * . a 



An example using the -v option follows: 



$ cscc -v scriptl 

EMPOWER/CS VI. 0.1, Serial#ROOOOO-000 , Copyright PERFORMIX, Inc. 1988-95 

cc -s -L/opt/oracle/lib -cckr -I/usr/ local/h -o scriptl . /csccl7377 . c 
/usr/local/lib/empowercsm.a /usr/ local/ lib/ empower csMON . a /usr/ 
local /lib/ empower GV. a /usr/local/lib/oralib.a /usr/local / lib/sybstub. a 
/usr/local/lib/syb4stub.a -locic /opt/oracle/lib/osntab . o -lsqlnet 
-lora -lsqlnet -lcv6 -lcore -lnlsrtl -lcore -lsocket -lnsl -Im 



5.4 Cscc Compilation Messages 

Cscc generates error messages under the following conditions: The script can not 
be read, the EMPOWER/CS environment variable is not defined properly, or the 
preprocessed version of the script can not be read 

The following error message is generated when the script can not be read or does 
not exist* 



$ cscc example 1 

Cscc: EMPOWER/CS VI . 0 . 1 , Serial#ROOOOO-000 , Copyright PERFORMIX Inc' 
1988-95 

cscc: can't open examplel.c. 
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The following error message is generated when the EMPOWER/CS environment 
variable is not defined properly: 



$ cscc examplel 

Cscc: EMPOWER/CS VI . 0 . 1 , Serial#R0OOOO-000 , Copyright PERFORMIX Inc 
1988-95 

cscc: can't find empowerm.h 



If the printf () function is incorrectly included in a script as print (), the 
following error message is generated: 



Cscc: EMPOWER/CS 


VI. 0.1, Serial#RO00O0-O0O, Copyright PERFORMIX, Inc. 


1988-95 


cc -s -o examplel 


. /csccl0965.c /usr/local/lib/* .a 


Id: 




Unresolved: 




print 





If you run Cscc to create a binary file called examplel while a script called 
examplel executes, you will receive the following error 

Bus error (coredump) 

All other error messages displayed during Cscc execution are generated by the C 
compiler. Compiler error messages will indicate the line number in the script that 
caused the error. 

Example: 



$ cscc examplel 

Cscc: EMPOWER/CS VI . 0 . 1 , Ser ial#R00000 - 000 , Copyright PERFORMIX Inc 
1988-95 

cc -s -o examplel . /csccl4137 . c /usr/local/ lib/ * . a 

cfe: Error : examplel .c: 48 : Missing ')' in macro instantiation 
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6.0 Script Execution 

Two methods are available for executing a script: Non-Display and Display modes. 
Non-Display mode executes what was captured between the PC and the SUT but 
involves only the UNIX script driver and the SUT. Display mode involves the PC, 
the UNIX driver, and the SUT and displays the captured client/server activity on 
the PC 



If you did not specify -h in the cscc command, you can access syntax help for a 
compiled script by entering the script executable name followed by a hyphen (-). 

Example: 



$ examplel 

examplel: EMPOWER/CS VI . 0 . 0 , Serial#ROOOOO-000 , Copyright PERFORMIX, Inc. 

1988-95 

Usage: 

examplel [-d hostname] [-S scriptid] [log [argl arg2 . . .]] 
Options: 

-d hostname Displays script execution 

-S scriptid Changes scriptid from example30 if not run from MIX 

log Identifies the log file to be created 

argl arg2 . . . Identifies optional script arguments 



Notes : 



If a log is not specified,- the log examplel . 1 will be created. 
If you specify " n as . the log, no log will be created. 
You must specify a log if you want to specify arguments, 
argl is accessible as the variable argv[3] in the script. 



6.1 Non-Display Mode 

Executing a script in Non-Display mode requires only the UNIX script driver and 
the SUT. The script on the UNIX driver replaces the PC to interact with the SUT, 
and the SUT responds as if it is servicing requests from an actual PC. 
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Executing EMPOWER/CS scripts from the UNIX script driver allows you to set up 
multi-user emulations by duplicating scripts or combining and executing multiple 
scripts. Refer to the Multi-User Testing manual for detailed information on 
executing multi-user emulations with EMPOWER/CS. 

To execute a script in Non-Display mode, you must first compile it on the UNIX 
script driver with the cscc command 

The script file created by Cscc is a binary executable file. Therefore, you can 
execute a compiled script in Non-Display mode by typing the name of the script 
(with no extension) at the command line with a series of options, listed in the 
syntax help screen above. 

To execute the script example30, type the following at the command line: 
$ example30 



6.2 Script Execution in Display Mode 

Since the UNIX script driver replaces the PC during script execution, you are not 
required to display emulated user activities during script execution. However, script 
development and debugging often are easier if you can see the emulated activity. 
Therefore, you can display captured user and database activity on one or more PCs 
as a script executes. Each PC that you wish to display to must have a network 
connection to the. UNIX script driver and to the SUT. 

In Display mode, script execution is initiated from the UNIX script driver. The UNIX 
driver directs the PC to replay captured user activity and to wait for data returned 
from the SUT. The PC replays the entire script interacting with the SUT as directed 
by the UNIX script driver. During script execution, all interaction occurs between 
the UNIX script driver and PC, and between the PC and the SUT. The SUT receives 
all PC transmissions and responds accordingly to the PC. 



EMPOWER/CS-Vl.O.1 



Copyright PERFORM! X. Inc. © 1995 



User's Guide— Script Development 



Before a script can be replayed, or executed, in Display mode, you must compile 
the script on the UNIX driver machine with the cscc command. 

You also must set up the PC to display the script If your Windows application is not 
already running, from DOS on the PC, type "win" to start MS Windows. 

When the Program Manager appears, select the EMPOWER/CS program group. 
Then, select the Display program-item icon: 






iUflMfliio 
Capture 
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*0 



The following window will open that displays a cartoon PC "listening" for network 
connections from the UNIX script driven 



Display 



File Help 



4l 



The UNIX driver must connect to the PC to execute the script and control the 
captured PC activity. On the UNIX script driver, enter the executable script name 
with the -d option and the name of the PC to which you are displaying. 

Example: 

$ scriptl -d vagrant 

Every user interaction that was captured between the PC and the SUT will execute 
on the PC. The UNIX driver directs the PC to activate windows, select buttons, enter 
queries, etc. as if a real user were using the PC. The PC in turn will interact with the 
SUT as it would if a real user were using it. The SUT will respond to the PC 
accordingly. 

The Display icon on the Windows screen will disappear during script execution and 
will return only when the script exits. 
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As soon as the script has completed execution, the computer cartoon will appear 
again "listening" for any other connections. If you have completed script execution 
in Display mode, simply select Stop in the Display window. 



6.3 Script Execution Options 

The options listed in the syntax help screen are described in the following sections. 



6.3.1 -d 

This option is used only for Display mode script execution. On the UNIX script 
driver, enter the executable script name with the -d option and the name of the PC 
to which you are displaying. 

Example: 

$ scriptl -d vagrant 

See Section 6.2 above for further Display mode instructions. 



6.3.2 Changing the Script ID 

When you execute a compiled script, a variable called script id is defined as the 
name of the script. If you execute a script called queryl, the variable scriptid 
would be given the value, queryl. 

With the -s option of the script execution command, you can change the value of 
scriptid. 
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Example: 

$ examplel -S example2 

The scriptid variable is used in Monitor and can be used within a script If you 
are running a multi-user test that executes a single script several times 
simultaneously, you should change the Script ID for each instance of the script. The 
Script ID acts as an emulated user ID. 

Note: If you are using the Mix tool, you do not need to specify the -s option to 
execute a multi-user test Mix inserts the -s option automatically by reading the 
Script ID from the Mix table. (Refer to the Multi-User Testing manual for more 
information on the Mix table.) 



6.33 Specifying a Log File 

When a script executes, a log file is created in the current directory on the UNIX 
driver. This log file contains all emulated user activity, SQL requests to the SUT, and 
all data returned to the PC. To calculate response times, this log file also includes 
time stamps for the time that such functions as Begin func t ion () , 
Endf unction { ) f Beginscenario { ) , and Endscenario ( ) were executed. 

If you do not specify a name for the log file in the script execution command, the 
log file will be given the same name as the script with a ". l" extension. You do not 
need to include the " . 1" extension if you specify a log file name. 

Example: 

$ example30 -d vagrant log 

When you specify a log file name, you can include a path name to save the file in a 
directory other than the current directory. 
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Example: 

$ example30 -d vagrant /user / empower/ logs / logO 0 1 

You also can define the e_logdir environment variable to specify a directory for 
log files as shown below: 

In the Bourne shell: 

$ E_LOGDIR=/user/empower/logs; export E_LOGDIR 



O 

m 



5=£ 



In the C shell: 

$ setenv E_LOGDIR "user /empower/ logs " 

If you do not wish to create a log file, specify the null string (- - ) as part of the 
script execution command which is useful for performing demos when disk space 
is limited. If you do not create log files, you will not be able to obtain statistical 
information for your test 

Example: 



$ example30 -d vagrant 



63.4 Specifying Arguments 

Arguments may be passed to the script during execution by specifying them in the 
script execution command. You must specify log file names prior to specifying 
arguments, even if you wish to use the default log file name. 
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Example: 

$ example 3 0 example 3 0.1 john passOOl 
Refer to Section 73 of this manual for more information on script arguments. 



6.4 The Log File 

Executing EMPOWER/CS scripts results in the creation of a log file for each 
executed script. If a script is executed so that the created log file has the same 
name as an existing log file, the new log file will overwrite the existing one. If you 
are running a multi-user test, you must ensure .that each emulated user writes to a 
different log file. 

The log file contains copies of user entries, every EMPOWER/CS function 
entered, SQL requests to the SUT, data returned to the PC, and time stamps used 
for performance measurement Entries in the log file that correspond to lines in the 
script source file include the characters >>> followed by the line number of the 
corresponding script file entry. 

The following is an example EMPOWER/CS log file: 
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>>> 




Log: scriptl.l 


>>> 




Date: Fri Jan 20 10:03:02 1995 


>>> 




Command: script 1 -d ergy 


>>> 




Beginsource ( " scriptl " ) 


>>> 


4 


Typerate(5.00) 


>>> 


5 


Pointerrate{150. 00) 


>>> 


6 


Thinkuniformd . 000, 2 . 500) 


>>> 


7 


Seed(28310) 


>>> 


8 


Timeout (300, CONTINUE ) 


>>> 


9 


Dberror (CONTINUE) 


>>> 


10 


Unset (NOTIFY) 


>>> 


12 


Beginscenario ( " scriptl " ) 10:03:02.89 


>>> 


14 


InitialWindow(0, "Desktop" , 0, 0 , 1024 , 768) 


>>> 


15 


InitialWindowd, "Program Manager " , 943 , 162 , 186, 581) 


>>> 


16 


InitialWindow (2 , "Accounting" , 413 , 679 , 1029 , 771 ) 


>>> 


18 


LeftButtonPress (448, 692) 


>>> 


21 


AppWait (0.05) 


>>> 


22 


WindowRcv ( "CwPtPt " ) 


CwPtPt 






>>> 


24 


LeftButtonPress (459, 616) 


>>> 


26 


WindowRcv ( "DwCoSf CwCwCwCwCwCwCwCwCwCwSf AcSzPt " ) 


S f S f Ac P t DwCoCwCwCwCwCwCwCwCwCwCwS z 


>>> 


28 


CurrentWindow( "Run" , 429 , 491, 880, 764 ) 


>>> 


30 


Think 1.923 


>>> 


33 


LeftButtonPress (470, 575) 


>>> 


35 


Type( "c: \acct\acct A M" ) 


>>> 


37 


AppWait (0 .22) 


>>> 


38 


WindowRcv ( " CwCwCwCwCwCwCw M ) 


>>> 




Username(LOGl, " scott / tigerQSUT" ) ; 


>>> 




Password ( LOG1 , n " ) ; 


>>> 




Logon ( ORACLE , LOG1 ) ; 


CwCwCwCwCwCwCw 


>>> 


97 


Think' 2.141 


>>> 


98 


ButtonPushf "Employee Records | Next " , 739, 438) 


>>> 


99 


ButtonPush( "Employee Records | Next " ,739, 438) 






( continued on following page ... ) 
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ButtonPush ( "Employee Records |Next " , 739 , 438) 
ButtonPush ( "Employee Records | Close" , 718, 157 ) 
WindowRcv( "Sf PtDwAcSf " ) 

CurrentWindow( "Accounting Application" , 189 , 82, 685 , 449) 
Think 1.069 

Lef tButtonDown ( 204 , 105 ) 
LeftButtonUp(211, 241) 
AppWait (0.39) 
WindowRcv( "ScDwAcSf " ) 

Commit ( LOG1 ) ; ScDw 

CurrentWindow( "Accounting" ,413,679,1029,771) 
Close (CURl) ; 
Logoff (LOG1) ; 
WindowRcv( "Pt H ) 

Endscenario ( "scriptl " ) 10 : 04 : 20 . 11 
Endsource ( ) 



The UNIX script driver drives the PC, instructing it to activate buttons and keys, to 
draw windows, to enter data, etc. according to functions in the script In the above 
script, those types of user interactions are marked with line numbers which refer 
back to a particular line in the script .c file. Because this script was executed on the 
PC in Display mode, you will notice that some lines in the log file contain no 
numbers corresponding to lines in the source script 

When a script is executed in Display mode, database traffic is generated by the PC, 
not the UNIX script driver. This traffic is captured and sent to the UNIX driver to be 
logged in the log file, but because these database functions were not executed by 
the UNIX driver, they contain no line numbers. 

If the script had been executed in Non-Display mode from the UNIX driver, its log 
file would include line numbers with the database functions because the UNIX 
driver interacts with the SUT just as a PC would. An example follows: 



>>> 


100 


>>> 


101 


>>> 


103 


SfAcSf PtD 


>>> 


105 


>>> 


107 


>>> 


109 


>>> 


110 


>>> 


113 


>>> 


114 


AcSf 




>>> 




>>> 


116 


>>> 




>>> 




>>> 


125 


Pt 




>>> 


127 


>>> 
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>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 

>>> 



Log: scriptl.l 

Date: Fri Jan 20 10:12:23 1995 
Command: scriptl 
Beginsource( "scriptl" ) 

4 Typerate (5 . 00) 

5 Point errate (150.00) 

6 Thinkuniform(1.000,2.500) 

7 Seed(28544) 

8 Timeout (300, CONTINUE ) 

9 Dberror (CONTINUE) 
10 Unset (NOTIFY) 

12 Beginscenario( "scriptl" ) 10:12:23.94 

14 InitialWindow(0, "Desktop" , 0 , 0 , 1024 , 768 ) 

15 InitialWindowd, "Program Manager ", 943 , 162 , 186 , 581 ) 

16 InitialWindow( 2 , "Accounting" , 413 , 679 , 102 9 , 111 ) 
18 Lef tButtonPress (448, 692) 

21 AppWait (0.05) 

22 WindowRcv ( "CwPtPt " ) 

24 LeftButtonPress (459, 616) 

26 WindowRcv ( "DwCoSf CwCwCwCwCwCwCwCwCwCwS f AcS z Pt" ) 

28 Cur rent Window ( "Run" ,429, 491, 880, 764, Nor) 

30 Think 1.288 

33 LeftButtonPress (470, 575) 

.35 Type("c: \acct \acc t"M" ) 

37 AppWait (0.22) 

3 8 WindowRcv ( " CwCwCwCwCwCwCw " ) 

39 Openenv(ORACLEl, V6|V7) 

41 Username (LOG1, " scott/ tigeriSUT" ) 

42 Password (LOG1, "") 

43 Logon (ORACLE, LOG1) 



>>> 
>>> 
>>> 
>>> 
>>> 
>>> 
>>> 
>>> 



97 Think 2.026 

98 ButtonPush( "Employee Records | Next ", 739 , 43 8 ) 

99 ButtonPush( "Employee Records | Next ", 739 , 438 ) 

100 ButtonPusM "Employee Records | Next " , 739 , 43 8 ) 

101 ButtonPusM "Employee Records | Close" , 7 18 , 157 ) 
103 WindowRcv ( " Sf PtDwAcSf." ) 

105 CurrentWindow( "Accounting Application" , 1 89 , 82 , 685 , 449 ) 

107 Think 1.008 



( continued on following page ...) 
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>>> 


109 


Lef tButtonDown<204, 105) 




>>> 


110 


Lef tButtonUp(211 , 241) 




>>> 


113 


AppWait (0.39) 




>>> 


114 


WindowRc v { n ScDwAc S f " ) 




>>> 


116 


CurrentWindow{ "Accounting* 


\ 413, 679,1029,771) 


>>> 


118 


Commit (LOG 1) 




>>> 


121 


Close (CUR1) 




>>> 


122 


Logof f (LOG1) 




>>> 


123 


C los env { ORACLE ) 




>>> 


125 


WindowRc v( "Pt" ) 




>>> 


127 


Endscenario ( "scriptl" ) 10 


12:55.53 


>>> 




Endsource ( ) 





if* 



.3* 



6.5 What Comes Next? 

Now that you have learned the basic concepts for emulating captured activity by 
executing a script, you are ready to begin a multi-user emulation. However, before 
proceeding to the Multi-User Testing Manual, you may wish to edit or enhance 
your scripts to emulate more realistic loads on your client/server system. The 
following section, Script Content and Enhancement, discusses common script 
functions, methods for editing your scripts, and advanced emulation techniques that 
allow you to develop realistic scripts. 
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7.0 Script Content and Enhancement 

Because your script .c file is a C language program and contains EMPOWER/CS 
functions, it can be edited to provide additional control over script execution. This 
section describes EMPOWER/CS script functions, various methods for editing 
your scripts, and advanced techniques for developing sophisticated scripts. 

Because extensive use of C language statements in EMPOWER/CS scripts 
constitutes advanced load testing, we recommend that you become proficient with 
all EMPOWER/CS tools before applying the concepts presented in this section. 



7.1 Script Content 

The following example is a typical EMPOWER/CS script (Note: Some content is 
left out for brevity): 

/* EMPOWER/CS VI. 0.1 Remote Terminal Bnulator Script */ 

Typerate(5); /* Typing delay in CPS */ 

Pointerrate{150) ; /* Pointerrate in PPS V 

Thirikuniform<l,2.5) ; /* Think delay */ 

Seed(getpid{) ) ; /* Seed random number- generator */ 

Timeout (300, CONTINUE) ; /* What to do if DB transaction takes too long V 

Dberror {CONTINUE) ; /* What to do on Database errors */ 

Unset (NOTIFY) ; /* Don't display warnings. I'll use Mon to find them */ 

Beginscenario ( " scripti " ) ; 

InitialWindow(0, "Desktop" ,0,0, 1024 , 768) ; 
InitialWindowd, "Program Manager" , 943 , 162 , 186, 581) ; 
InitialWindow(2, "Accounting" , 413 , 679 , 1029, 771) ; 

LeftButtonPress(448, 692) ; 



AppWait{0.05) ; 
WindowRcv( "CwPtPt" ) ; 



( continued on following page ... ) 
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LeftButtonPress(459, 616) ; 



WindowRcv( "DwCoSfCwCwC\^OX^^<^^^ ; 



Cur r entWindow ( ■ Run ",429,491,880,764); 



Think(2.53) ; 

/* Clicked (Edit) */ 
LeftButtonPress(470,575) ; 

Type ( "c : \\acct\\acct~M" ) ; 



AppWait(0.22) ; 

WindowRcv( "0^jC^X^^<^A<^X^vCw• ) ,- 
Op en en v (ORACLE 1 , VERSIONV6V7 ) ; 

Username(LOGl, "scott/tiger(iSUT" ) ; 
Password ( LOG1 , " tiger " ) ; 
Logon ( ORACLE 1 , LOG1) ; 

WindowRcv( "SfAcSfDwPtPtPtPtPtPtPtPtPtPtPtPtPt" ) ; 
CurrentWindow( 'Accounting* , 413 , 679 , 1029 , 771) ; 
Open ( LOG 1, CURD ; 
WindowRcv ( " AcSf " ) ; 

CurrentWindow ( "Accounting Application", 189,82,685,449), 
Think(4.89) ; 

ButtonPush( "Accounting Application | Customers ", 343 , 288) ; 



AppWait(5.72) ; 

WindowRcv( " Sf PtCwCwCwCwCwCwC^y<\^^ ) ; 

Begintimer( "Accounting Application_Customers" ) ; 
Dbset (CURl , DEFER, TRUE) ; 

Parse (CUR1, n SELECT ID, FIRST_NAME, LAST_NAME , ADDRESS_LINE_1 , ADDRESS_LINE_2 , 
ADDRESS_LINE_3 , PHONE_NUMBER , FAX_NUMBER, COMM__PAID_YTD, ACCOUNT_BALANCE , COMMENTS 
FROM CUSTOMERS " ) ; 

DescribeAlKCURl, 1, 12); 

Dbset (CURl, MAXARRSIZE, 64) ; 
Define(CURl, "1", STRING, 40); 
"Define(CURl, "2*, CHAR, 21); 
Define(CURl, "3", CHAR, 21); 
Define(CURl, "4", CHAR, 21); 

( continued on following page ...) 
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Define (CUR1, 
Define (CUR1, 
Def inetCURl, 
Define (CUR1, 
Define (CUR1, 
Define (CUR1, 
Def ine(CURl, 
Exec (CURD; 



"5", CHAR, 21); 
"6', CHAR, 21); 
"7", CHAR, 16); 
-8", CHAR, 16); 
"9", STRING, 40); 
"10", STRING, 40); 
"11", CHAR, 241); 



DbsettCURl, FETCHSIZE, 64); 
Fetch (CURD ; 

while (GetNextRow(CURl) !=NOMOREROWS) ; 
Endtimert "Accounting Application_Customers" ) ; 
WindowRcv("AcSfSfPt") ; 



CurrentWindow ( " Employee Records " , 73 , 82 # 790 , 506 ) ,* 
Think (18. 13) ; 

ButtonPusht "Employee Records | Next ", 739 , 438) ; 



AppWait(2.57) ; 
WindowRcv ("SfPt") ; 



Think (7. 80) ; 

ButtonPush( "Employee Records (Next" , 739, 438) ; 
But tonPush( "Employee Records (Next 739 , 438) ; 
ButtonPush( "Qnployee Records |Next" , 739,438) ; 
ButtonPush( "Employee Records | Close 718, 157) ; 

WindowRcv ( " S f PtDwAcS f " ) ; 



CurrentWindow ( "Accounting Application" # 189, 82 , 685 , 449) ; 



Think(4.23) ; 



LeftButtonDown(204,105) ; 
LeftButtonUp(211,241) ; 



AppWait(0.39) ; 
WindowRcv ( " Sc DwAc S f " ) ; 

CurrentWindow ( "Accounting" , 413 , 679, 1029, 771) ; 

Beg in timer ( "Accounting" ) ; 
Commit (LOG1) ; 

( continued on following page . . . ) 
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Close (CURD ; 
Logoff (LOG1) ; 
Closenv (ORACLE 1) ; 

WindowRcv ( " Pt " ) ; 

End timer ( "Accounting" ) ; 

Endscenario ( m scriptl " ) ; 



7.1.1 General Script Functions 

y3 Descriptions of general EMPOWER/CS script functions are presented in the 

following sections. 



7.1.1.1 Begin/End Functions 

EMPOWER/CS has three sets of 'Begin" and "End" functions which mark the start 
and finish of scenarios and functions. These functions are BeginscenarioO, 
Endscenar io ( ) , Beg in f unction ( ) , End function (), Beg in timer () , and 
Endtimer ( } . 

The parameter for each function is the name of the script section being defined. 
Each "Begin" function must have a corresponding "End" function and the 
parameter used in each "Begin" function must match the name used in the "End" 
function. 

The BeginscenarioO and Endscenario ( ) functions cause scenario time stamps 
to be recorded in the log file. These functions are inserted into the script .c file 
automatically during Capture to mark the beginning of the script Scenarios typically 
define large sections of emulated activity. Usually an entire script represents a 
scenario. 
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The Beginf unction ( ) and Endf unc t ion ( ) functions are inserted by the 
EMPOWER/CS user during Capture or during script editing to define specific 
activity as a C function. These functions cause function time stamps to be recorded 
in an executed script's log file which allows the Report tool to calculate response 
time statistics for the function. The Report tool will indicate the response time for 
executing the entire set of activities in the function. 

The Begintimer ( ) and Endtimer () functions are inserted into the script 
automatically during Capture if the Insert Timer option is specified or manually by 
the EMPOWER/CS user. They are used to calculate response times for the 
activities they define. If Insert Timer is selected, Begintimer () and Endtimer ( ) 
are placed around database traffic that occurs between two user events in the 
script. If Insert Timer is not selected, the user can insert these functions to specify 
activity to be measured in the script 



7.1.1.2 Typerate and Pointerrate 

A high fidelity emulation of PC user activity should include a simulation of the time 
required to type at the keyboard. EMPOWER/CS allows you to specify a typing 
speed, measured in characters per second, that is applied to all emulated keyboard 
activity. 

The Typerate () function sets the typing speed. During script execution, each 
time that the emulated user is supposed to be typing at the keyboard, the script will 
pause a length of time defined as the number of characters to be typed times the 
type rate specified. For example, if the emulated user must type twelve characters 
and the type rate is specified as six characters per second (Typerate (6)) then the 
script will pause two seconds when the emulated characters are to be "typed." 

The default function , Typerate (5) , is placed at the top of every script created by 
EMPOWER/CS, specifying a type rate of 5 characters per second. You may change 
this rate during script editing. If you specify a type rate of zero in the script 
(Typerate (0)), then no delay is used when the script emulates a user typing at the 
keyboard. 
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EMPOWER/CS applies the type rate by inserting a delay between each emulated 
typed character listed in the Type ( ) function. For example, if the emulated type 
rate is five characters per second and five characters are to be sent to the SUT, 
EMPOWER/CS will pause 1 second between each character. 

The type delay is applied using UNIX system functions particular to your UNIX 
machine. Each delay technique may include some inaccuracy of up to 0.5 seconds. 
This inaccuracy over the course of a type-intensive script may affect the duration 
of script execution, the actual type rate, and ultimately, the accuracy of the 
performance statistics. 

EMPOWER/CS keeps track of the difference between the specified type rate and 
the actual type delay. This difference is known as typing drift. Throughout script 
execution, EMPOWER/CS compensates for typing drift by adding to or reducing 
type delays as appropriate. 

Other supported delay methods on your UNIX machine are nsdelay, sleepdelay, 
pseudodelay, and selectdelay. nsdelay is accurate to 0.01 seconds. The 
sleepdelay method uses the sleep (2) system call, which is accurate only to 0.5 
seconds, pseudodelay allocates a pseudo port on the machine for delays. It is 
accurate to 0.1 seconds. If the machine runs out of pseudo ports, the delay is 
applied with sleepdelay. selectdelay, which is used for BSD systems, uses the 
select (2) system call and is accurate to 0.01 seconds. Although other delay 
methods are available, the most accurate delay method on your UNIX script driver 
is that used by EMPOWER/CS. 

An accurate representation of PC user activity also should include a simulation of 
the time required to move the mouse. EMPOWER/CS allows you to specify a 
speed for mouse movements, measured in mouse points per second, that is 
applied to all emulated mouse activity. 

The Pointerrate ( ) function specifies the points per second that the mouse 
pointer moves. During script execution, each time that the emulated user is 
supposed to move the mouse, the script will pause a length of time defined as the 
number of points moved times the pointer rate specified. For example, if the 
emulated user points the mouse to 120 locations and the pointer rate is specified as 
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60 points per second (Pointerrate(60)) then the script will pause for 2 seconds 
when the emulated mouse movements are executed. The pointer rate delay is 
similar to the concept of type rate delay as described above. 

The default function, Pointerrate(lOO), is placed at the top of every 
EMPOWER/CS script, specifying a pointer rate of 100 points per second. You may 
change the default value during script editing. If you wish to use no pointer rate 
delay during your emulation, specify Pointerrate(O). 

During script execution, EMPOWER/CS applies the emulated pointer rate by 
inserting a delay between each point that the mouse should move. In Display mode, 
you will notice that the mouse pointer will pause during each pointer movement 
from one specified location on screen to the next 



7.1.1.3 Think Time Functions 

Think time functions insert pauses in script execution to emulate when a user 
pauses to think before continuing to interact with the PC These pauses are 
represented by the Think ( ) , Thinkactual ( ) , Thinkconstant ( ) , Thinktne ( ) , 
and Thinkunif orm( ) script functions. The Think () function specifies when a 
pause should be inserted during script execution. Thinkactual ( ) specifies that 
actual captured think times should be used. The other three functions define the 
length of the think delay by specifying a think time distribution. 

The Think ( ) function, which may appear throughout the script, will cause the script 
to pause its execution according to the most recently defined think time 
distribution. 

During Capture, you may specify the number of seconds that EMPOWER/CS will 
wait before inserting a Think { ) function into the script file. The Think ( ) function 
is inserted in the captured script file only after the specified time has elapsed. By 
default, if no activity is captured after two seconds, EMPOWER/CS will insert a 
think time function of at least two seconds and the time elapsed until the next 
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action occurs. The parameter of the Think () function specifies the number of 
seconds elapsed. 

During script execution, Thinkac tual ( ) tells the script to use values in the 
Think { ) functions that were captured during your Capture session. The following 
example demonstrates using this function within a script. When you edit your 
script, insert Thinkac tual ( ) as shown below: 



./* EMPOWER/CS VI. 0.1 Remote 


Terminal Emulator Script */ 






Typerate (5) ; 


/* 


Typing delay in CPS */ 






Pointerrate(lSO) ; 


/* 


Pointerrate in PPS */ 






Thinkac tual ( ) ; 


/* 


Think delay */ 






Seed{getpid( ) ) ; 


/* 


Seed random number generator */ 






Timeout(300, CONTINUE); 


/* 


What to do if function takes too 


long 


*/ 


Dberror (CONTINUE) ; 


/* 


What to do on Database errors */ 






Unset (NOTIFY) ; 


/* 


Don't display warnings. I'll use 


Mon 


to find them * / 


Beginscenario ( " examplel 










Think time distribution 


may 


be defined with any of these three 


think 


time 



functions: Thinkcons t ant (), Think tne () , and Thinkuni form () . Varying think 
time distribution throughout a script is common and, typically, each application will 
have its own think time distribution. These functions define a distribution of 
randomly chosen think time amounts and can be inserted more than once 
throughout the script file when editing your script Because the script was captured 
with think time values, a value must be specified in Think ( ) functions for script 
execution (even if the value is zero), regardless of the think time distribution. 

Thinkcons tant ( ) specifies that the think time is the same every time a Think ( ) 
function is encountered. The think time amount is specified by the parameter 
constant. The syntax is: 

Thinkconstant (constant) 
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ThinktneO defines a truncated negative exponential distribution of think time 
amounts. The parameters specify the minimum, average, and maximum: 

Thinktne (min, avg, max) 

Thinkuniform( ) defines a uniform think time distribution. Think time amounts 
will be chosen so that they are evenly distributed between the amounts specified 
by the parameters min and max: 

Thinkunif orm(min, max) 

Random number generation for EMPOWER/CS functions is provided by a random 
number generator internal to the EMPOWER/CS software. Random number 
generation is required for the EMPOWER/CS functions Range!), 
Thinkunif orm( ) , and Thinktne ( ) . The EMPOWER/CS internal random number 
generator will provide consistent results for all UNIX platforms. 

If the same range parameters and seed value are provided for Ranged, 
Thinkunif orm{ ), and Thinktne ( ), the same random number will be generated 
every time. To ensure unique random numbers, you should use the Seedd 
function to seed the random number generator uniquely for each user. The 
example script at the beginning of this section shows the use of the Seed() 
function where the process ID is used as a seed for the random number generator. 



7.1.1.4 Timeouts and Database Errors 

The Timeout ( ) function specifies how long EMPOWER/CS will wait to receive an 
expected response during script execution. When a matching response is not 
received in the specified time, the script is said to "time out." The Timeout {) 
function specifies the length of time to wait before a timeout and the action to be 
taken when the script times out The syntax for the function is: 

Timeout (n, cond) 
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Similarly, the DberrorO function specifies the action to be taken if a database 
error occurs. The syntax is: 

Dberror (cond) 

The parameter n in the Timeout () function is the number of seconds to wait 
before a timeout (an integer). The cond parameter in both Timeout () and 
Dberror ( ) is the action to be taken at timeout or database error. This parameter 
can be either continue or exit or a user-defined function, continue specifies 
that script execution continues to the next function in the script and is generally the 
condition specified, exit halts script execution. 

The default functions, Timeout (300, CONTINUE) and Dberror (CONTINUE), are 
placed at the top of every script created by EMPOWER/CS. During script 
execution, Timeout (300, continue) specifies that the script will wait 300 
seconds (five minutes) for the expected response, then continue. 
Dberror (continue) specifies that the script will continue if it enounters a 
database error. You can edit these functions and/or insert them throughout the 
script to suit your testing needs. 

The following conditions may cause timeouts or database errors to occur during 
script execution: 

O If a script times out and continues prematurely, receipt of the "late" response 
(meaning the response took longer than the specified 300 seconds) likely will throw 
script synchronization off, which could cause continual timeouts until the script 
exits. If your SUT is slow, you may need to increase the timeout value. 

O When multiple clients are accessing the SUT during script execution, responses to 
your script(s) or PC (in Display mode) could be delayed. 

O During script execution in Display mode, EMPOWER/CS waits for specific 
WindowRcv( ) patterns. If the expected windowRcvt J patterns are not received in the 
specified time, a timeout will occur. 
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O The state of the SUT during script execution may not be identical to its state during 
Capture (e.g., if the script tries to delete a record in the database that already has 
been deleted) which could cause unexpected responses to be received by the script 
or PC 

O Processing a database function may take longer than the specified timeout time. 

Timeouts and database errors can be identified by observing script execution in 
Display Mode or Monitor and by inspecting the log file. The following example 
shows a portion of a log file containing a timeout. In this example, the script timed 
out on a windowRcv( ) function and because the timeout condition was continue, 
the next script function was executed. 



>» 27 AppWait (0.05) 

»> "28 WindowRcv( " Sf PtDwAcPtPtPtPtPtPtPtPtFtAcSf " ) 

Sf PtAcAcSf P^tDwPt 

»> Timeout 16:18:12.25 

»> Needed: PtPtPtPtPtPtPt 

>>> Buf fer:SfSfAcSf 

»> 30 CurrentWindow ( "Sample Application" , 189 , 82 , 68 5 , 449 ) 

>» 32 Lef tButtonDown(213, 105) 

»> 33 LeftButtonUp(212, 105) 



7.1.13 Set and Unset 

To aid in creating sophisticated script files, various EMPOWER/CS options are 
available during script execution. The set ( ) and Unset ( ) functions allow you to 
specify certain activities and settings for your emulation. These functions can be 
inserted or changed when you edit your script 

Set ( ) turns on EMPOWER/CS options during script execution, unset ( ) turns off 
EMPOWER/CS options during script execution. 
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Valid options are listed below: 

Option Description 

lcmd log miscellaneous commands 

flush flush SUT responses to the log that are detected after a pattern 

match in s windowRcv( ) 

nobuf don't use buffered writes to the log file 

notify display a message when a timeout occurs, execution is 

suspended, or execution resumes 

bell ring the bell twice when a timeout occurs 

logging Enable logging 



7.1.1.6 Mouse Activity 

The following list shows all the functions used to emulate mouse button activity for 
the left, middle, or right mouse buttons during script execution: 



Lef tButtonDown (x, y ) 
Lef tButtonUp (x,y) 
Lef tButtonPress (x, y) 
Lef tDblPress (x, y) 



MiddleButtonDown (x , y ) 
MiddleButtonUp (x, y) 
MiddleButtonPress (x,y) 
MiddleDblPress (x,y) 



RightButtonDown (x, y) 
RightButtonUp (x, y) 
RightButtonPress (x,y) 
RightDblPress (x, y ) 



These functions are inserted into the script .c file during Capture when the 
specified mouse activity is performed. 

The function parameters x,y indicate the xy coordinates of the mouse on screen at 
the time the mouse button was activated during Capture. 

The "ButtonDown" functions indicate when the specified button on the PC mouse 
was pressed down. 
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The "ButtonPress" functions indicate when the specified button on the PC mouse 
was pressed down and released. A ButtonPress event is inserted in the script when 
a ButtonDown and ButtonUp event do not contain other user events between them 
and the x,y coordinates are the same. 

The "ButtonUp" functions indicate when the specified button on the PC mouse was 
released. This function will be captured into the script file instead of a ButtonPress 
function if the x,y coordinates are different between two consecutive down/up 
mouse activities. 

The "DblPress" functions indicate that the user double-clicked a mouse button. 
During script execution, these functions emulate two consecutive presses and 
releases of the specified button. 

During script execution in Display mode, these functions are used to emulate the 
specified mouse activity. In Non-Display mode, the x,y coordinates are used to 
simulate moving the mouse by emulating a mouse pointer delay to the next x.y 
coordinates. 

Mouse button events may be edited in your script file, but because you change the 
activity from when it was captured, you run the risk of breaking the script. 



The following example script segment contains various mouse button activities: 



AppWait(5.21) ; 




WindowRcv( "Pt" ) ; 




LeftButtonDown(213, 111) ; 




AppWait(0.55) ; 




WindowRcv ("Pt") ; 




Lef tButtonUp (222, 195) ; 






(continued on following page . . .) 
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AppWait(0.38) ; 
WindowRcv( "Pt M ) ; 

Lef tButtonDown{340, 216) ; 
Lef tButtonPress { 33 3 , 219 ) 



AppWait (0.17) ; 
WindowRcvf M Pt" ) ; 

Lef tButtonPress (350, 202) ; 



01 



7.1.1.7 Keyboard Activity 

The following list shows the functions used to emulate keyboard activity during 
script execution: 



KeyPress (key) 

KeyDown(key) 

KeyUp(key) 



Sys KeyPress (key) 
Sy s Key Down ( key ) 
SysKeyUp (key) 



The parameter key represents a Microsoft Windows virtual key code value. All 
possible virtual key code values are listed below: 



VK_TILDE 


VK_LAPPOST 


VK_UNDERS< 


VK_HYPHEN 


1 VK_PLUS 


VK_EQUAL 


VK_LCURLY 


VK_LSQUARE 


VK_RCURLY 


VK_RSQUARE 


VK_COLON 


VK_SEMI 


VK_DQUOTES 


VK_SQUOTES 


VK_LTHAN 


VK_COMMA 


VK_GTHAN 


VK_PERIOD 


VK_QUESTION 


VK_SLASH 


VK_PIPE 


VK_BKSLASH 


VK_CANCEL 


VK_CLEAR 


VKJTAB 


VK_BACK 


VK_SHIFT 


VTC_CONTROL 


VKlMENU 


VK_PAUSE 


VK_CAPITAL 


VK_ESCAPE 


VK_SPACE 
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VK_PRIOR 


VK WPYT 


Viv tlNJU 


VK_HOME 


l/Tf T PPT 


-VK__UP 


VK RIGHT 


V rv LMJWiN 


VK_SELECT 


VK EXECUTE 


\TY CM A DCUHT 


VK — INSERT 


VK DFT.FTF 


vK w nc,IjF 


VK_NUMPADO 


VK MTIMPAm 


V rv_lN UM P ADz 


VK_NUMPAD3 


VK MTTMP ADd 


\7V MT TM 7\ f \ C 

vK_NUMPADb 


VK_NUMPAD6 


VK MTTMPAD7 


V fv_l\ U M P AD o 


VK_NUMPAD9 


VK MTTT.TTPTY 




VK_SEPARATOR 


V I\. O U 13 1 fvrtk- 1 


VK_DECIMAL 


VK„DIVIDE 


vis. r ± 


VK_F2 


VK_F3 


VK__F4 


VK_F5 


VK_F6 


VK__F7 


VK_F8 


VK_F9 


VK_F10 


VK_F11 


VK_F12 


VK_F13 


VK_F14 


VK_F15 


VK_F16 


VK_F17 


VK_F18 


VK_F19 


VK_F20 


VK_F21 


VK_F22 


VK_F23 


VK_F24 


VK_NUMLOCK 


VK_SCROLL 





These functions are inserted into the script during Capture when the specified key 
activity is performed. 

The "KeyDown" functions indicate that a non-printable keyboard key on the PC was 
pressed down. 

A "KeyPress" function is translated into a KeyDown/Up sequence. A KeyPress 
function is captured into the script when no user events are contained within a 
KeyDown/Up pair. 

The "Keyllp" functions indicate that a non-printable keyboard key on the PC was 
released. 

The "SysKey" functions indicate that the keyboard activity included pressing the 
Alt key. "Sys" implies that the keystrokes are being sent to the System Menu of 
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the current window which is located under the icon in the top left corner of the 
window as shown below: 



Empower/CS 



Move 




Size 




Minimize 




Maximize 




Close 


Ctrl+F4 


Next 


Ctrl+F6 



Tools 



During script execution in Display mode, these functions are used to emulate the 
specified keyboard activity. In Non-Display mode, type rate is applied to these 
events and the script delays accordingly. 

Key events may be edited in your script file, but because you change the expected 
activity from when it was captured, you may break the script when it is executed. 

The following example demonstrates various keyboard and mouse activity in a 
script file: 



Beginscenario ( " example2 " ) ; 
Lef tButtonPress (188, 381) ; 

WindowRcv { 'XwPtPtDwCoSf CwCwCwCwCwCwCwCwCwCwSf AcSzPt M ) ; 

(continued on following page . . .) 
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Lef tButtonDown(193 , 316) ; 
LeftButtonUp(193 ,317) ; 

CurrentWindow { " Run" , 189,82,685, 449 ) ; 

AppWait (0 . 11) ; 

TypeC'crWacctWcWacct^" ) ; 
WindowRcv( "CwAcSf DwPt " ) ; 

CurrentWindow ( "General Ledger", 234, 99,704,520) ; 



AppWait (1.26) ; 



Sys Key Down (VK_MENU) ; 
SysKey Press (VK_SPACE) ; 
SysKeyUp(VK_MENU) ; 

Type ("scott^I tiger A IFOO^M M ) 



7.1.1.8 Type 



The Type { ) function is recorded into a script file during Capture when keystrokes 
are entered from the keyboard The parameter of the Type ( ) function may include 
the standard keyboard keys pressed (except for those defined as virtual key codes 
in Section 7.1.1.2) and the non-displayed key combinations defined below. Each key 
translates into a KeyDown/Up pair for the emulation. 



Non-displayed key combinations are shown in the parameter of the Type ( ) 
function using the standard UNIX technique in which the character " represents the 
Control key. Common control sequences captured into the Type ( ) function are 
listed below: 

~M Carriage Return 

Backspace 

Tab 
~? Delete 
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Note: You may notice that if you use the number pad or a symbol font during your 
Capture session, the numbers or symbols will not be captured into the Type ( ) 
function. For instance, if you are using a symbol font where the "A" key represents 
"a", pressing this key will be captured as Type ("a"). To capture numerical 
characters, you should use those listed at the top of the standard keyboard. Only 
standard keyboard keys are captured into a script .c file. 

During script execution in Display mode, the Type ( ) function is used to emulate a 
user typing the specified keystrokes. In Non-Display mode, this function emulates 
a typing delay. 

Type strings are very easy to modify and can be edited to alter the keystrokes 
typed by an emulated user. For example, the following Type ( ) function is entered 
in a query: 

Type( H 13402^M M ) ; 

It can be modified to: 

Type( M 98704"M W ) ; 

The following example shows a portion of a script containing a Type ( ) function in 
which the user entered a command during Capture to run an application: 



AppWait (0.11) ; 

Type( n c:\\acct\\c\\acct A M M ) ; 
WindowRcv( "CwAcSf DwPt" ) ; 

CurrentWindow( "General Ledger" , 189, 82, 685, 449) ; 



Note: If executing your script in Non-Display mode, any modifications you make 
to the Type ( ) function will not affect the data that is input to the database. It will 
only affect the amount of type delay to be emulated. If you do want different data to 
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be input to the database, you will need to change the corresponding Parse ( ) or 
DataO statements. 



"•4 



7.1.1.9 ButtonPush 

The ButtonPush () function is inserted into the script file during Capture to 
indicate that a specific button, a MS Windows pushbutton such as OK, Cancel, Yes, 
No, etc., was activated. It is used during script execution in Display mode to move 
the mouse to activate the specified pushbuttons. In Non-Display mode, this function 
simulates mouse movement as defined in the x,y parameters to allow for mouse 
pointer delay. 

The syntax of this function is: 

ButtonPush (str, x,y) ; 

The parameter str may be listed in a format similar to the following examples: 

ButtonPush ( M Program Manager | Run | OK ",226,99) ; 
ButtonPush ( "Tools | #cl | #c4 ",68,69); 
ButtonPush ("OK" , 187, 201) ; 
ButtonPush ( "#c2" , 299, 134) ; 

The format of the str parameter is designed so that EMPOWER/CS can easily 
locate the captured pushbutton during script execution in Display mode. This 
format is based on the MS Windows concept of a tree structure. 

The MS Windows tree structure is based on a heirarchy of windows where each 
window that is accessed from a primary, or parent, window is a child of that parent 
The str parameter is pipe-delimited, and is listed right to left from child to parent 
window where the right-most item is the name of the pushbutton. If one of the 
windows or the pushbutton has no title, something like "#cl" will be listed to 
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indicate the window is a certain numbered child of the preceding parent window. 
EMPOWER/CS will be able to locate the specified pushbutton by following the 
heirarchy listed in the str parameter. 

In the first example listed above, ok is the name of the pushbutton that was 
activated Run is the name of the window that contained this ok button, and Run was 
a child window of the parent window Program Manager. In the second example 
listed above, #c4 was the pushbutton activated and was the fourth child of the first 
child (#cl) of the Tools window. 

If the button's parent window is the active or current window, only the button will 
be listed in the str parameter. In such a case, you may notice ButtonPusM ) 
functions similar to the following in your script file which will follow a 
CurrentWindow( ) function: 

If you wish to edit this function in your script file and need to determine a button's 
tree structure, you can use the Tree Tool under EMPOWER/CS Tools. See. Section 
8.4 of this manual for more information on the Tree tool and the MS Windows tree 
structure. 

In the following example script segment, the user activated the ok pushbutton to 
open an application: 



CurrentWindow( "Run" , 189 , 82 , 685 , 449 ) ; 
Type ( "c:\\acct\\c\\acct A M) ; 
ButtonPush ( "OK" , 354 , 153 ) ; 



7.U.10 InitialWindow 

This EMPOWER/CS function is inserted into the script during Capture after the 
Beginscenario ( ) function. InitialWindow ( ) records the state of your Windows 
desktop by listing all active program windows at the time the Capture session 
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began. Therefore, if multiple applications are open when you begin Capture, 
multiple Initialwindow( ) functions will be listed in the script file. 

The following example demonstrates initialwindow( ) functions captured in a 
script file: 



Beginscenario { "scriptl" ) ; 

InitialWindow ( 0 , n Desktop" ,0,0,1024, 768) ; 
InitialWindowd, "Program Manager 989 , 34 , 232 , 453 ) ; 
InitialWindow{2, "MS-DOS Prompt" , 0,0, MAXWIDTH, MAXHEIGHT) ; 



The first parameter of the initialwindow( ) function indicates the position of the 
program in the MS Windows task list The program's position in the Windows task 
list is important for users who capture a script using "Fast-Tab" task switching. 
Position 0 is a reserved value; it is used to record the screen resolution during 
Capture and verify the resolution for script execution in Display mode. 

The second parameter identifies the title of the window. 

The next two numerical parameters indicate the x.y coordinates of the top left 
portion of the window on screen. Then, the next two parameters indicate the width 
and height of the window. If the width and height are both zero, the window is 
minimized. If the x,y coordinates are both zero, and width is maxwidth and height 
is maxheight, the window is maximized. If neither of these conditions apply, the 
window is in a normal state. 

During script execution in Display mode, InitialWindow ( ) attempts to locate the 
windows listed as parameters and place them in their captured positions. The 
function does not apply to Non-Display mode script execution. 

If the specified programs are not open at the time of script execution or if a 
window could not be moved to the specified position, the log file will record a 
warning but script execution will continue. Therefore, before you execute your 
script in Display mode, your desktop should have the same applications open as 
when you captured the script 
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You should not attempt to remove or edit this function in your script file because 
you would change the state of the Windows desktop from when it was captured, 
and, therefore, may break the script. 

Note: The first ini tiaiwindow { ) function listed in the script indicates the 
resolution of the screen as the first xy parameters are 0,0. You will notice a task 
order of 0 specified in this first initialwindow( ) function. The zero indicates to 
EMPOWER/CS to check the screen resolution making sure the script is displayed 
in the same resolution as captured. For instance, if a script was captured in VGA 
mode and you attempted to display it in SuperVGA mode, the captured xy 
coordinates would be invalid. Therefore, when displaying your script, you should 
use a screen that is the same resolution as the screen used during Capture. 

• ^% 

Sj 7.1.1.11 AppWait Delay 

^ The AppWait ( ) function is inserted into your script file during Capture before a 

J* windowRcv ( ) function to record the amount of time taken to draw a window on 

U screen. This function is used during script execution to emulate the application 

Gl delay for drawing a window on screen. During script execution, this function only 

IX applies to Non-Display mode, because in Display mode, windows would actually be 

activated. 



In the following example, the script recorded an application delay of 1.16 seconds to 
draw the "Program Manager" window. During script execution in Non-Display 
mode, the script will emulate the application delay by pausing the script for the time 
specified. 

The parameter of AppWaitO is the time in seconds of the captured application 
delay. If you wish to change your AppWait delay, you may set a multiplication factor 
with the AppWaitFactor ( ) function. This function multiplies the AppWait delay 
times the factor. For instance, during script execution your application may be 
twice as slow because it is receiving twice as much data from the SUT. You can set 
the AppWaitFactor ( ) to 2 so that the script will emulate the extra delay. 
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Example: 



AppWaitFactor (0.20) ; 
AppWait (1.16) ; 

WindowRcv( "SfDwAcSfSf Sf Pt* * ) ; 



7.U.12 WindowRcv 

The WindowRcv () function is inserted into the script during Capture when an 
activated window is drawn on screen and usually follows an AppWaitO call. 
^ Consecutive WindowRcv ( ) functions can be listed within the script file. 

ft 

§ This function is used during script execution in Display mode to ensure that the 

^ activated window is drawn on screen. In Non-Display mode, this function is ignored 

because the AppWait ( ) function emulates the amount of time required to draw the 
specified window. 

The parameters of this function are MS Windows standard two-letter pneumonics 
that represent the following commands: 

Command Description 

Ac Activate Window 

Co Command 

Cw Create Window 

Dw Destroy Window 

Pt Paint 

sf Set focus 

Sz System Command 



EMPOWER/CS-Vl.O.1 



7-23 

Copyright PERFORMIX. Inc. © 1995 



User's Guide— Script Development 



Example: 



AppWait(0.05) ; 

WindowRcv( " CwPtPtDwCoSf CwCwCwCwCwCwCwGwCwCwS f AcSzPt " ) ; 
WindowRcv( " PtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPt " ) ; 

CurrentWindow( "Run" , 429, 491 , 880, 764) ; 



This function should not be edited in your script file when displaying script 
execution because you change expected activity from when it was captured and, 
therefore, run the risk of breaking the script 

J} 7.1.1.13 CurrentWindow 

%j The CurrentWindow { ) function is inserted into your script file to record all titled 

^0 windows that were activated during the Capture session. This function is used to 

% ensure windows are in their captured state during script execution in Display 

E mode. It will be listed in Monitor during script execution in Display and Non-Display 

H> modes adding context to script execution. 

r=n 

n I 

The parameters Of CurrentWindow ( ) identify the title of the current window 
(window with focus), define the top left xy coordinates, and then, define the width 
and height of the window's position on screen. If the width and height are both 
zero, the window is minimized. If the x,y coordinates are both zero and width is 
maxwidth and height is maxheight, the window is maximized. If neither of these 
conditions apply, the window is in a normal state. 

During script execution, if the window could not be moved to the specified 
position, the log file will record a warning but script execution will continue. 




The following example demonstrates how CurrentWindow ( ) would appear in a 
script file. The activated window was "Accounting" which appeared on screen in a 
normal state: 
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AppWait(0.39) ; 
WindowRcv ( " ScDwAcSf ** ) ; 

CurrentWindow{ "Accounting" , 413 , 679 , 1029 , 771 ) ; 



The following example is a portion of a log file that recorded a warning when a 
Currentwindow( ) function could not execute properly because the window did 
not exist during script execution in Display mode: 

»> " CurrentWindow( "File Manager ",0,0, MAXWIDTH , MAXHEIGHT ) 
Warning: Unable to find window 

This function should not be edited or removed from your script file because you 
change the state of your Windows desktop from when it was captured and, 
therefore, run the risk of breaking the script. 



f 7.1.2 Interacting with the SCIT 

p For you to fully understand the process of interacting with the SUT and the 

[jjj EMPOWER/CS functions associated with this process, the general behavior of the 

z; database environment should first be explained. The following paragraphs and 

p sections will introduce you to levels of the database environment that represent 

specific database communication structures, define the actual script statements that 
represent such operations as querying or inserting data, and describe other 
EMPOWER/CS functions that perform various database operations. 



7.1.2.1 Communication Structures 

In the database environment, certain communication structures are defined to 
access the database on the server for retrieving, inserting, or changing data. These 



EMPOWER/CS-Vl.O.1 



7-25 



Copyright PERFORMIX. Inc. 0 199S 



User's Guide— Script Development 



communication structures must be accessed in a particular order as explained 
below: 

O The first level of the database environment is the database environment as a whole. 
An entire environment is defined that identifies the database being accessed. 

O The next level is a log on communication structure. To connect to the database, at 
least one log on communication structure is defined. If the client application 
requires multiple, simultaneous connections, one log on structure is defined for each 
connection. 

O The third level of the database environment is the cursor structure. To process SQL 
requests to the SUT, a cursor communication structure is defined for each SQL 
request 



In your captured script .c file, you will notice such parameters to various database 
functions as oracle, logi, log2, curi, cur2, etc. These parameters are identifiers 
of each level of the database environment that was opened to access the SUT. Each 
level is numbered to link all database operations particular to a certain environment, 
log on, or cursor structure. For example, the call Exec(CURl) would execute the 
Parse { ), or SQL, statement that belongs to the cursor, curi. 



The following diagram demonstrates the database environment structure and how 
the SUT is accessed. 
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Accessing the SUT 



Database Environment 



LOG1 



LOG2 



CUR1 



CUR2 



CUR3 



CUR4 



SQL 



SQL 




SQL ?m0&h- 



SUT 



7.1.2.2 Procedure for Interacting with the SUT 

Interaction with the SUT occurs when SQL requests are sent to the SUT and then 
processed. SQL requests are represented in the script by the parameter to the 
Parse { ) function which lists a SQL statement 

To access and interact with a database on the server during script execution, 
EMPOWER/CS database functions are called in a particular order. The 
EMPOWER/CS database functions will occur in the script generally based on the 
following standard procedure: 
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Basic Procedure and Script Structure for Database Activity 

□ A database environment is opened, represented by the call Openenv ( ) in 
the script which specifies the database to be accessed 

□ A connection to one or more databases occurs with a Logon { ) to each 
specified database 

□ One or more cursors are opened, represented by the Open ( ) function in the 
script, to process SQL statements 

□ The SQL statements required to perform database operations such as 
querying, inserting, or deleting data are processed with Parse ( ) 

□ The select-list items of the SQL statement are described as necessary with 
Describe () functions 

□ Bind( ) functions are called for input statements to bind the address of an 
input variable to each placeholder in the SQL statement 

□ For queries, Define ( ) is called to define an output variable for each select- 
list item in the SQL statement 

□ Exec ( ) is called to execute the Parse { ) and, therefore, the SQL statements 

□ For queries, Fetch () and GetNextRowO are called to retrieve and sort 
through specified rows of data 

□ The cursors are closed with close ( ) 

□ A Logoff () function is called for each log on structure to disconnect from 
the specified database(s) 

□ Each database environment is closed with Closenv ( ) 
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The following script segment demonstrates the EMPOWER/CS functions used to 
interact with the SUT: 



Type ( "c : \\accts\\accts~M" ) ; 




AppWait(0.22) ; 




WindowRcv ( "Cv^nOaCwCwCwCw" ) 




Openenv ( ORACLE , VERSIONV6V7 ) ; 


Username(LOGl, "scott/tiger@FOO" ) ; 


Password ( L0G1 , " tiger • ) ; 




Logon { ORACLE , LOG1 ) ; 




WindowRcv ( ■ Sf AcSf Dw' ) ; 




Op en ( LOG 1, CUR1) ; 




WindowRcv ( • AcS f - ) ; 




CurrentWindow( "Accounts Application - , 189, 82, 685, 449) ; 


Think (4. 77); 




ButtonPush( "Accounts Application] #c5" , 355 , 270) ; 


AppWait<5.38) ; 




WindowRcv ( " Sf CwCwCwCwCwCwCv^CwCvX^X^X^^<^tf " ) ; 


Dbset (CURl , DEFER, TRUE) ; 




Parse (CUR1, ■ SELECT ID, FIRST_NAME, LAST_NAME , ADDRESS_LINE_1 , ADDRESS__LINE_2 , 


ADDRESS_LINE_3 , PHONE_NUMBER , FAX_NUMBER, COMM_PA I D_YTD , ACCOUNT_BALANCE , COMMENTS 


FROM CUSTOMERS ■ ) ; 




DescribeAlKCURl, 1, 12); 




Dbset (CURl, MAXARRSIZE, 64); 


Define{CURl, "1", STRING, 40); 


Define(CURl, "2", CHAR, 21) 




Define(CURl, "3", CHAR, 21) 




Define (CURl, "4\ CHAR, 21) 




Define (CURl , "5", CHAR, 21) 




Define(CURl, "6" , CHAR, 21) 




Define (CURl, "7", CHAR, 16) 




DefinetCURl, n S m , CHAR, 16) 




Define (CURl, "9", STRING, 40); 




( continued on following page . . . ) 
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Define(CURl, "10", STRING, 40); 
Define(CURl, "11-, CHAR. 241); 
Exec (CURD ; 

Dbset(CURl, FETCHSIZE, 64); 
Fetch (CURD ; 

while (GetNextRow (CURl ) ! =NOMOR£ROWS) ; 



Commit (LOG!) ; 



Close (CURD ; 
Logoff (LOGl) ; 
Closenv (ORACLE) ; 

Endscenario ( "scriptl" ) ; 



■*g The following sections further explain the procedure for interacting with the SUT. 

SI 

ss»s 

= 7J.2.3 Open an Environment 

fy As stated in the previous section, the first level of the database environment is the 

m database environment as a whole. This level is represented in a script file by such 

Q database names as oracle, sybase2, etc. and is accessed with the function 

^ Openenvf). The Openenv ( ) function is inserted into the script when a database 

environment is opened. When executing a script, OpenenvO opens an 
environment to specify the database and database version to be used for the 
emulation. 

In some cases, multiple databases may be accessed and activity for each database 
may occur concurrently, therefore, more than one Openenv ( ) call may be listed 
within a script. 
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7.1.2.4 Connect to the SCJT 

The second level of the database environment is the log on level which opens a 
connection to the SUT through a log on communication structure. This level is 
defined with a Logon { ) call in the script and is represented in function parameters 
as a pointer to a log on structure called LOGl, L0G2, etc. The first log on structure 
defined will be numbered by EMPOWER/CS as logi, the second as LOG2, etc. 

The Logon ( ) function is inserted into the script when a log on connection is 
opened to the database. The parameters to Logon ( ) specify to which database the 
script is connecting and the number of the log on structure. 

P The script establishes communication with one or more databases by calling a 

^ Logon ( ) function for each connection. Logging on to the database is necessary for 

\h the subsequent database operations of querying and inserting data. Multiple log on 

M structures are possible for each database environment 

To successfully access or log on to the database, a Usemame and Password also are 
defined. Therefore, before a Logon () function executes, the Usemame () and 
Password ( ) functions are called in the script Usemame ( ) sets the name of the 
user who is logging on to the database and the Password () function sets the user 
password to log on to the database. These functions are inserted into the script file 
when a user name and password are entered to log on to the database. 

The following script segment demonstrates the process of logging on to the 
database, oraclei, from the log on structure logi: 



Typepc : \\accts\\accts A M M ) ; 
AppWait {0 .22) ; 

WindowRcv ( " CwCwCwCwCwCwCw " ) ; 
Openenv { ORACLEI , VERSI0NV6V7 ) ; 

Us er name (LOGI , " scot t/ tiger @FOO" ) ; 
Password ( LOGI , " t iger M ) ; 
Logon (ORACLEI, LOGI) ; 
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Mote: In some cases, you also may notice the functions, AppName ( ) , Hostname { ) , 
and ServernameO before the Logon () call in your script. These functions also are 
used to. access the database. AppName ( ) specifies the name of the database 
application being used. HostName( ) specifies the name of the host machine where 
the server resides. Servername ( ) is the name of the server on the host machine 
where the database is located. 



7.1.23 Open the Cursors 

The third level of the database environment is the cursor communication structure. 
The cursor structure is where the script actually interacts with the database by 
processing SQL requests to the SUT. Cursors are opened with an Open{ ) call in 
the script file and are represented in function parameters as a pointer to a cursor 
structure called curi, CUR2, etc. The first cursor opened in a particular log on 
structure will be numbered by EMPOWER/CS as curi, the second as CUR2, etc. 
The Open ( ) function is inserted into the script when a cursor structure is opened. 

A cursor can be opened only through a successful log oh connection and multiple 
cursors can be opened from a single log on. Processing a SQL statement is 
possible only from an open cursor structure. Therefore, such script functions as 
Parse ( ) , Define ( ) , Bind ( ), Exec ( ), Fetch ( ), GetNextRow( ), etc. which process 
the SQL statement operate only from a cursor structure. The SQL statement is a 
parameter to the Parse {) functions and specifies the operations of querying, 
inserting, or deleting data 

The Open { ) function will be listed after the Logon ( ) function and before the 
Parse ( ) in your script file. 




7.1.2.6 Parse the SQL Statement 

Parsing the SQL statement associates it with the appropriate cursor in the script. 
Parsing a SQL statement includes sending it to the SUT, verifying its syntax is 
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compatible with the database, and preparing the SUT for subsequent operations 
specified in the SQL statement. The Parse {) function is inserted into your script 
when a SQL statement is parsed and sent to the SUT. Every SQL statement in a 
script must be parsed with the Parse () function. Once a Parse () is performed, 
the parsed statement is stored on the database to wait for an Exec ( ) call. 

The first parameter of the Parse ( ) function identifies the cursor structure that was 
opened with the associated Open ( ) function. The second parameter lists the SQL 
statement to be parsed 

The SQL statement specifies the set of data that is to be operated on by the 
database. This statement is a request to the SUT to select, input, delete, update, or 
retrieve data. Subsequent functions (i.e, Define < ) , Bind ( ) , Exec ( ) , Fetch ( ) ) 
designate how to perform the database operations and reference the SQL 
statement by listing the associated cursor number in a function parameter. 

Because the SQL statement can be executed only from a cursor structure, Parse ( ) 
occurs after an Openf) function; and, because the SQL statement is executed by 
the Exec { ) function, Parse ( ) occurs before Exec { ) in the script 

In the following example, the SQL statement for the cursor, CUR1, begins with " 
select This example demonstrates a Parse () function selecting data for a 
database query: 

Parse (CUR1, " SELECT ID, FIRST_NAME, LAST_NAME, ADDRESS_LINE_1 , 
ADDRESS_LINE_2, ADDRESS_LINE_3 , PHONE — NUMBER , FAX_NUMBER, 
COMM_PAID_YTD, ACCOUNT_BALANCE, COMMENTS FROM CUSTOMERS M ); 

The following example demonstrates a sample SQL statement for inserting data: 

Parse (CUR1, "INSERT INTO CUSTOMERS ( ID, FIRST_NAME, LAST_NAME , 
ADDRESS_LINE_1 , ADDRESS_LINE_2 , ADDRESS_LINE_3 , PHONE_NUMBER , 
F AX_NUMB E R , COMM_PAID_YTD, ACCOUNT_BALANCE , COMMENTS ) VALUES ( 
789 , 'Robert' , 'Adams', '1 Maple Lane*, 'Anytown', *VA, 22222*, 
•555-9856', '555-7634', 500, 700, 'Good Job' ) M ) ; 
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The following example demonstrates a sample SQL statement for deleting database 
records: 

Parse (CUR1, "DELETE FROM CUSTOMERS WHERE ID = 789 AND FIRST_NAME = 
'Robert' AND LAST_NAME = 'Adams 1 AND ADDRESS_LINE_1 = *1 Maple 
Lane' AND ADDRESS_LINE_2 = 'Any town' AND ADDRESS_LINE_3 = 'VA, 
22222' AND PHONE_NUMBER = '555-9856' AND FAX_NUMBER = '555-7634' 
AND COMM_P A I D_YTD = 500 AND ACCOUNT_B ALANC E = 700 AND COMMENTS = 
'Good Job 1 * ) ; 

Note: If you are using ah older version of an Oracke database, you may notice the 
Sql ( ) function in your script file instead of Parse ( ) . The Sql { ) function is 
identical to Parse ( ) except that it does not allow for a deferred parse. See Section 
p 7.13.1 for more information on deferred parses. 

*j9 • 7.1.2.7 Describe Select-List Items 

J* If a description of a variable in a SQL query statement was requested by the client 

application during Capture, a Describe { ) function will be inserted into your script 

O file. The variable is specified in the function's parameter by a cursor number and 

by the variable s position in the SQL statement. The Describe () function will 

^ occur in the script after a Parse ( ) statement and before Define ( ) . 

P 

During script execution, Describe () sends a request to the database for a 
description of specified select-list items in the SQL statement. It returns 
information about the select-list items needed to determine how to convert, display, 
or store the data that will be returned when rows are fetched for a query. Such 
returned information can include the name of the variable, the data type, the size of 
the item, whether the data is null-terminated or updateable, etc. 

Note: If you notice the function DescribeAll ( ) in your script, a Described 
operation was performed describing every select-list item listed between two 
positions. 
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Example: 

DescribeAll (CUR1 , 1 , 12 ) ; 

In this example, all variables listed in the SQL statement from curi, starting from 
position 1 to position 12, will be described. 

In some cases, you may notice a Descr ibeProc ( ) function instead of 
Describe {). The DescribeProc ( ) function describes all variables used in a 
specified stored procedure. A stored procedure is an operation that is stored on 
the database to be executed later. The procedure must be described before a parse 
is completed. Therefore, this function will occur in the script before Open ( ) and 
r=*3 Parse (). 

yl 

7.1.2.8 Bind the Addresses of Input Variables 

Some SQL statements require that data be input to the database. Placeholders for 
input variables in the SQL statement mark where specific data must be input and 
are indicated by leading colons (Example: : name). If a SQL statement requires data 
to be input to the database, a Bind ( ) function will be inserted into the script to bind 
each placeholder to a variable that is to be passed to the database. Therefore, when 
the SQL statement is executed, the database will receive the data that was placed in 
the input variables. 

The parameters of the Bind ( ) function identify the variable by the cursor number 
of the associated SQL statement, the variable placeholder listed in the SQL 
statement, the variable's data type, and the variable's length in bytes. 

The Bind( ) function is listed in the script after a Parse ( ) statement and before 
Exec ( ) . 
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The following example demonstrates a BindO function inserted into a script for 
the variable, x: 



Parse (CUR1, " SELECT EMPNO, ENAME, JOB, MGR, HIREDATE, SAL, COMM, 
DEPTNO FROM EMP WHERE EMPNO=:X"); 



Bind(CURl, M X n , STRING, 10); 



Note: If you notice a BindpO function in your script, a BindO operation was 
performed for a variable based on its position in the SQL statement instead of 

p placeholder name. The parameter would specify a position instead of a name. 

^0 BindpO binds the variable's position to the variable. 

h 

If a variable was inserted and then retrieved, the BindDefineO function is 
inserted into the script. BindDefineO inputs a variable to the database and then 
gets a new value. Usually, the value returned is the old value. For example, if the 
SQL statement specified that the value Smith be inserted into a record to 
overwrite the existing value Jones, BindDefineO would specify Smith as the 
new value for the record and then return the old value Jones to the variable. 




7.1.2.9 Define 

The Define () function is inserted into the script when output variables are 
defined for storing data to be fetched from the database. The SUT places data in 
these output variables when a Fetch () function is called. Define ( ) functions are 
used only when fetching records from the database for a query. 

Define () associates the address of an output variable in the program with each 
select-list item in a SQL query statement. The Define () function defines each 
select-list item in the SQL statement by a cursor number, the item's position in the 
SQL statement, the variable's data type, and the variables length. The positions in 
the SQL statement are defined beginning with 1 for the first (or left-most) select-list 
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item, 2 for the second, and so on. The Defined function is listed in the script 
after a Parse ( ) statement and before Fetch { ) . 

The following script segment demonstrates the Define () statements defining 
variables for each select-list item of the SQL statement. Notice in the first 
Define () statement below, the variable position "i* refers to id in the SQL 
statement 



ft 

^0 



Parse (CUR1, " SELECT ID, FIRST_NAME, LAST_NAME, ADDRESS_LINE__1 , 
ADDRESS_LINE_2 , ADDRESS_LINE_3 , PHONE_NUMBER, FAX_NUMBER, 
COMM_PAID_YTD, ACCOUNT_BALANCE, COMMENTS FROM CUSTOMERS w ) ; 

DescribeAll (CUR1, 1 , 12); 



Dbset (CUR1,MAXARRSIZE, 64) ; 



Define (CUR1, M l", 

Define (CUR1, M 2" , 

Define (CUR1, "3\ 

Define (CUR1, "4" f 

Define (CUR1, "5 W , 

Define (CUR1, "6" , 

Define (CUR1, "7", 

Define (CUR1, "8 W ( 

Define (CUR1, "9", 

Define (CUR1, "10" 

Define (CUR1, "11" 
Exec ( CUR 1) ; 



STRING, 40); 
CHAR, 21) 
CHAR, 21) 
CHAR, 21) 
CHAR, 21) 
CHAR, 21) 
CHAR, 16) 
CHAR, 16) 
STRING, 40); 

STRING, 40); 

CHAR, 241); 



7.1.2,10 Execute the Parse 

The Exec ( ) function executes the operations specified in the associated SQL 
statement. This function is inserted into your script when a SQL statement is 
executed on the SUT. 
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Exec ( ) executes the SQL statement by specifying the data the script will be 
fetching or by inputting the values in ail bind variables to the database. 

The parameter of Exec { ) identifies the cursor of the associated SQL statement. 

7.1.2.11 Fetch the Rows of Data for a Query 

After the specified output variables are defined and the SQL statement has been 
executed, the rows of data that satisfy a query are fetched. In your script, the 
Fetch () function is inserted when the data specified in the SQL statement to 
satisfy a query is retrieved. During script execution, when the number of rows of 
p data specified in the option fetchsize is fetched from the database, the data is 

^ placed into the defined output variables in a buffer on your UNIX script driver 

^ machine. The parameter of Fetch{) specifies the cursor structure for the 

Ci associated SQL statement 

-v: 

% The number of rows of data that are fetched is specified in the Dbset ( ) function 

J~ in the following format: 

M= 

O Dbset (curnum, FETCHSIZE, n) 

ru 

p*I The parameter fetchsize sets the number, n, of rows of data to fetch. See Section 

p 7.13.1 for more information on setting the fetchsize. 

Each Fetch ( ) statement returns the next row from the set of rows that satisfies a 
query. After the last row has been returned, the next fetch will return an error that 
no remaining rows could be fetched. 

The Fetch { ) statement is called only after the Parse ( ) and Exec ( ) functions have 
been called. 
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In the following script segment, Fetch { ) is called for the cursor, curi: 



Parse (CUR1, " SELECT EMPNO, ENAME, JOB, MGR, HIREDATE, SAL , COMM, 
DEPTNO FROM EMP , FOR UPDATE OF EMPNO , ENAME, JOB, MGR, HIREDATE, 
SAL, COMM, .DEPTNO" ) ; 



Exec (CURI) ; 
Fetch (CURD ; 



if* 



note: If you notice a FetchRaw( ) function in your script, this function signifies 
that binary data was specified in the SQL statement to be retrieved. FetchRaw( ) is 
used because the data is too large to transfer across the network at one time. 
Instead, the data is transferred in portions at a time. The parameters to FetchRaw( ) 
identify the cursor number of the associated SQL statement, the position of the 
associated select-list item in the SQL statement, the data type of the output variable, 
and the length in bytes of the data to be retrieved 



In your script file you also will notice the function GetNextRow( ) which is inserted 
after Fetch(). The GetNextRow() function is inserted into the script when the 
client application sorts through the fetched rows of data. 

During script execution, GetNextRowt ) is used to view the contents of the fetched 
rows of data one at a time after they are fetched onto the UNIX script driver. This 
function generally occurs in a loop and may be used to verify that the requested 
data was retrieved or to locate a specific row of data. 



The following example demonstrates calling GetNextRow( ) in a script file: 



Fetch (CURD ;. 

while (GetNextRow(CURl) ! =NOMOREROWS ) ; 
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7.1.2.12 Close the Cursor Structures 

Before a client application that processed SQL statements exits, each open cursor 
is closed Once a cursor is closed, no additional operations can be performed on 
that cursor. 



The EMPOWER/CS function, close ( ), is inserted into the script for each cursor 
structure that was closed. When an executing script exits, each cursor opened in a 
particular log on structure is closed with a close ( ) function (one for each open ( ) 
call). 



^ 7.1.2.13 Disconnect from the SGT 

Cj When a client application that processed cursors exits, each connection to the 

gQ database is closed. The Logoff () function is inserted into the script for each 

V connection to the database that was closed. All active cursors on the specified log 

^ on structure must be closed before the log on structure is closed. 

7.1.2.14 Close the Environment 

The function closenvO is inserted into a script file when a database environment 
is closed. 

A ClosenvO function closes each environment that was opened with each 
Openenv ( ) . After a database environment is closed, no further log on connections 
can be made within the specified database environment. Each database 
environment in a script must be closed before an executing script exits. 
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The following example demonstrates that the database environment oracle was 
closed: 



Close (CURl) ; 
Logoff (LOG1 ) ; 
Closenv (ORACLE) ; 

Endscenario ( " script 1 " ) ; 



7.1.3 Other Database Functions 

The following sections describe other EMPOWER/CS database functions that may 
appear in your script file. 



7.13.1 Dbset 

Client applications may specify certain options that control the behavior of the 
database environment The Dbset ( ) function is inserted into the script when such 
options are set according to the client application and the SUT and how they 
interact. This function may occur throughout a script and it specifies various 
options for the database environment 

The syntax for Dbset ( ) follows: 
Dbset (num, opt, value) 

The parameter num will be an environment number, a log on structure, or a cursor 
number; the parameter opt specifies the database option being set; and, value 
represents either a numerical or string value, or true or false, depending on the 
option being set. 
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The Dbset () options that commonly will show up in your scripts are defined 
below: 

Option Description 

fetchsize Specifies the number of records to fetch from the database 

when a Fetch ( ) function is executed. The Dbset ( ) function that 
sets the fetchsize will occur before a Fetch ( ). The fetchsize 
value can not be larger than the value specified for maxarrsize. 
If the fetchsize was specified as 50 and maxarrsize was 
specified as 20, EMPOWER/CS will reduce the fetchsize to 
20. The default value for this option is 1 which means that if 
fetchsize is specified as zero or lower, EMPOWER/CS 
automatically sets the value to 1. 

Sets the maximum array size for retrieving or inserting records. 
If the array size is set at 20, 20 rows of data can be inserted or 
fetched If this option is set at 20, then 20 placeholders are 
allocated for inserting or fetching 20 rows of data. The Dbset ( ) 
function that sets the maxarrsize will occur before the Bind ( ) 
and Define ( ) functions in a script The default value for this 
option is 1 which means that if maxarrsize is specified as zero 
or lower, EMPOWER/CS automatically sets the value to 1. 

Specifies the number of rows of data to be inserted into 
the database. This option will be listed before the Data ( ) 
function in a script in the format Dbset (curi , insertsize, 
n). This option allows array binding. For example, if n is 0 or 1, 
one row can be inserted at a time into the database. If n is 50, 50 
rows will be inserted into the database and 50 Data ( ) lines must 
be listed for every row before Exec( ). The insertsize value 
can not be larger than the specified maxarrsize. The default 
value for this option is 1 which means that if insertsize is 
specified as zero or lower, EMPOWER/CS automatically sets the 
value to 1. 

offset Specifies the offset for inserting records in an array. This option 

is used with the insertsize option. If an array includes four 
names and the offset is set to 2, the second name will be the 
starting point for inserting data. The Dbset ( ) function specifying 
this option will occur before an Exec ( ) function. If the offset is 
specified as a range larger than the maxarrsize, a database error 
will occur- 



%a MAXARRSIZE 



-4J 



INSERTSIZE 
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WAITRES 



^4 



DEFER 



Specifies whether or not to wait for resources. If this option is 
set to true, the script will wait indefinitely for requested 
information from the database. If it is set to false and the script 
does not receive the requested information, the script will 
receive an error that the resource was not available. Script 
execution will then either continue or exit based on the condition 
set in Dberror ( ) . The default value of this option is true. 

Specifies whether or not to defer the Parse ( ) statement 
If this option is set to true, a deferred parse will be performed 
when the script encounters the Parse ( ) function. If the option is 
set to false, a normal Parse ( ) is executed. The default value of 
this option is false. 

Normally, the SQL statement is sent over to the database when 
the script encounters Parse () and processed to ensure it is 
semantically correct The SQL statement is stored to wait for the 
Exec ( ) call that actually executes it If defer is set to true, the 
SQL statement is not sent over to the database until the script 
encounters an operation that requires input from the database 
such as Exec { ) or Describe { ) . 



= v 



A complete list of Dbset ( ) options that may appear in the script file is listed below 
with brief descriptions. This list is divided into those options that set integer values 
and those options that specify true or false. The list also designates the options 
that apply specifically to the database environment as a whole, to the log on 
structure, or to the cursor. 



Integer Value 



Option 



fetchsize 

maxarrsize 

insertsize 

OFFSET 

MAXCONNECT 

PACKETSIZE 

ROWCOUNT 

TEXTS I ZE 

ISOLATIONLEVEL 

AUTHOFF 



Description 

number of rows to be fetched 

maximum number of rows to be fetched or inserted 

number of rows to.be inserted 

row number where to begin inserting 

maximum number of connections in an environment 

maximum packetsize on logon connection 

maximum number of rows to return 

limit on size of text or image data 

transaction isolation level 

turns specified authorization off 
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turns specified authorization on 
security label specifies cursor read level 
security label specifies cursor write lev 
which day of week is first 
format of date 

disable inserts into table identity column 
enable inserts into table identity column 



AUTHON 

CURREAD 

CURWRITE 

DATEFIRST 

DATE FORMAT 

IDENTITYOFF 

I DENT IT YON 



TRUE or FALSE 



Option 



Description 



DEFER 

UPDATE 

READONLY 

SAVEOPTS 

FORCELOGOFF 

FORCEEXIT 

RECOMPILE 

RETPARAM 



deferred parse 

cursor is for updating 

cursor is read only 

do not deallocate the structure 

force logoff 

force exit 

recompile stored procedure before executing 
return parameter 



Database environment only 

truncate truncate data 

interrupt application can be interrupted 



Database environment or logon structure 



ansi_binds 

DEFER_IO 

ASYNC_IO 

SYNC_IO 

EXTRA_INF 

EXPOSE_FMTS 



force ansi style binds 
deferred io 
async io 
sync io 

return extra information for error 
expose formats 



Logon structure 

BULKCOPY 

ASYNCNOTIFICATION 

DIAGJTIMEOUT 

APPSECURITY 

SYBSECURITY 

ENC SECURITY 

TRUSTSECURITY 

AN SI NULL 

ANSI PERM 



allow bulk copy on connection 
asynchronous notification 
what to do on a timeout 
application defined security 
Sybase defined security 
encrtyped security 
trusted security 
ansi style nulls 
ansi style permissions 
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ARITHABORT 

ARITHIGNORE 

CURCLOS ETRAN 

NONSTANDSQL 

FORCEPLAN 

FORMATONLY 

GETDATA 

NOROWCOUNT 

PARSEONLY 

QUOTEDIDENT 

PARSETREES 

SHOWPLAN 

IOSTATS 

TIMESTATS 

IGNORETRUNC 



what to do on arithmetic errors 

what to do on arithmetic div. by 0 

close all cursors on end transactions 

flag non standard sql 

force plan or not 

only send format for data 

returns extra information on every sql statement 
row count 

only check syntax, do not execute 

all double quotes signify identifiers 

returns parse resolution trees 

generates a description of procedure plan 

return internal io statistics 

return time statistics 

ignore truncation errors 



-in 



Cursor. 

AUTOCOMMIT 
WAITRES 
SPECIAL 
HIDDEN KEYS 



commit on every exec 
wait for resources instead of error 
Sybase version of cursor . 
expose hidden keys 



W 7.1.3.2 Data 

: M 

y * 

p% The Data() function is used with database operations for inserting or updating 

p data. It specifies the data to be input to the database by listing the data for each 

input variable specified with Bind( ). Therefore, it will follow all Bind{ ) functions 
and will occur before Exec ( ) . This function is inserted into the script when data is 
specified to be input to the database. 

The str parameter is pipe-delimited and lists the data for each input variable that 
was defined with Bind{ ). The data listed in this str parameter will be listed in the 
same order as it was specified in the Bind( ) functions. 

The Dbset( ) option insertsize applies to this function in that the number of 
Data ( ) functions inserted will correspond to the value of insertsize. 
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Example: 



Parse (CUR1 


SELECT 


ENAME, 


EMPJOB , WHERE ENAME= : name . . 


. ) ; 


Bind (CURl, 


"NAME" , 


STRING, 


5) ; 




Data (CURl, 


" SMITH" ) 









In this example, smith is the data to be entered into the database for the cursor, 

CURl. 

In another example, a SQL statement may include the following: 

...EMPNO, ENAME, EMPJOB WHERE EMPNO= : empno , ENAME= : name , 
EMPJOB= : empjob. . . 

A Data ( ) line that refers to this SQL statement may look like the following: 
Data (CURl, " 123 | Smith | typist " ) 

12 3 would correspond to empno, Smith would correspond to ename, and typist 
would correspond to empjob. 

Because all users would not make the same entries to the database, you may edit 
this function to vary the data that is inserted into the database during multi-user 
emulations for a more realistic load. You can edit the Data ( ) functions in a set of 
scripts so that each emulated user inserts a different record. For example, if a 
Parse () statement contains where name = smith, and the Data() line is 
Data(CURl, "SMITH"), you could change this Data!) line toData(CURl, 
m jones h ) orData(cuRl, "ADAMS") for each emulated user. 
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7.13.3 SqlExec 



If you notice a SqlExec( ) function in your script, a SQL statement was executed 
that contained no input or output variables. The SqlExecO function includes four 
database operations. It opens a cursor, parses a SQL statement, executes the 
Parse ( ), and closes the cursor. When this function is used, no operations such as 
Describe ( ), Bind( ), DefineO, Fetch ( ), etc. are necessary. For example, it may 
be used when a database operation only requires joining two tables. 

The syntax for this function is: 

SqlExec ( lognum, sqlstmt) 

The lognum parameter designates the log on communication structure and 
sqlstmt lists the SQL statement 



The Commit () function is inserted into the script when database processing is 
committed to the database. This function commits to the database all processing the 
script has completed (i.e., updating records, deleting records, adding records, etc.) 
since processing was last committed to the database. Its parameter may specify a 
log on or cursor structure for which operations are committed. 

The Rollback {) function may be inserted into the script if database operations 
are not committed but are rolled back since data was last committed. Rollback ( ) 
restores the database to its original state since the last commit was executed. 

These functions may appear throughout the script dependent on the behavior of 
the client application and the SUT. 



7.1.3.4 Commit, Rollback 
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7.1.4 Editing Database Functions 



The EMPOWER/CS database functions. translate client application and database 
interaction and are inserted into the script as the associated actions occur. This 
process ensures that during script execution a load is generated on the SUT as 
close to the real interactions as possible. Because the EMPOWER/CS database 
functions are not user-defined but are inserted into your script based on how the 
client application interacts with the SUT, you generally should not attempt to edit 
these functions or remove them from the script 

Most of the database functions should not be edited because they are inserted 
during Capture in a way specific to the application running from the PC to the SUT. 
If you change these functions from when they were captured in the script file, you 
may drastically alter the expected behavior of the application and SUT and 
therefore, break your script during execution. 

However, simple edits can be made to some of the Dbset ( ) options and more 
complex edits can be made for the DataO and Parse ( ) functions to enhance 
multi-user emulations. 

Because all users would not make the same entries to the database, you may edit 
the DataO and Parse {> functions to vary the data that is inserted into the 
database during multi-user emulations for a more realistic load. You can edit the 
Data ( ) functions in a set of scripts so that each emulated user inserts a different 
record. 

The Dbset { ) option, fetchsize, can be changed to see how a larger or smaller 
fetchsize value affects the performance of your SUT during script execution. 
Please note that the fetchsize value can not be larger than the maxarrsize value. 
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7.1.5 Comments 

As with all C language programs, your script file should include comments to 
indicate the structure of the script. Comments also are useful for interpreting the 
log file. 

Comments are entered either during Capture or when editing your script file. They 
are enclosed by the /* and */ characters and may span multiple lines in a script, but 
may not be nested. 



7.2 Data Types 

The following is a list of the EMPOWER/CS data types that may be listed in the 
database script functions, Bind( ) and Defined. Format lists how the data types 
are represented in the script as C language data types. This format does not 
necessarily represent how the data type is converted and stored on the database. 



Type 

NUMBER 
DECIMAL 



Format 

Internal database binary 
Internal database binary 



Money and Date Data Types 



Type 

MONEY 

LONGMONEY 

DATE 

LONGDATE 



Format 

dollarsxents 

dollarsxents 

day/ month/ year hour:minute:seconds 



Example 
103 .45 
103 .4500 

02/10/95 10:06:35 



day /month/year hour:minute:seconds.milliseconds 02/10/95 10:06:35.23 



The format for the date data type must be 17 characters in length. The format for 
the longdate data type must be 20 characters in length. 



EMPOWER/CS-Vl.O.1 



7-49 

Copyright PERFORMIX, Inc. O 1995 




User's Guide— Script Development 



Numeric Data Types 



Type 


Format 


BYTE 


char 


SHORT 


short 


INT 


int 


UINT 


unsigned int 


DOUBLE 


double 


FLOAT 


float 


BOOL 


char 



For the remaining data types, the format specifies the maximum length for the 
character array. 



Non null- terminated characters 



Type 

LONGCHAR 
CHAR 
MEDCHAR 
SHORTCHAR 



Format 

char[2*31-5] 
char [2000] 
char [65535] 
char [255] 



Null- terminated strings 
Type 

LONGSTRING 

STRING 

SHORTSTRING 



Format 

char [2*31-1] 
char [2001-1] 
char [256-1] 



Binary data 
Type 

LONGBINARY 
SHORTB I NARY 
BINARY 
IMAGE 



Format 

char(2 A 31-l] 
char [256] 
char[65535] 
char[2*31-5] 



Encrypted data 
Type 

SECURITY1 
SECURITY2 



Format 
char[ ] 
char [2000] 
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7.3 Script Arguments 

Arguments can be passed to the script when the script is executed at the 
EMPOWER/CS command line or when a set of scripts is executed with the Multi- 
User testing tool, Mix. Arguments deliver information to a script to control how the 
script executes. 

Arguments may be used to send a random number seed to a script to control a 
random sequence of commands. You can pass the same seed value to a script to 
obtain the same sequence of commands. 

Arguments also may be used to control the execution of functions in the script You 
may have designed the script to contain functions that test different parts of your 
application. The argument can specify which functions execute at what time and in 
what sequence. 



7.3.1 Argument Syntax 

The script receives arguments as parameters when the script executes. Arguments 
passed to the script (which do not include options) are stored as variables in the 
argv[] array. The number of elements in the argvU array is defined by the 
variable argc. 

EMPOWER/CS will define these argument variables automatically as follows: 

int argc ; 
char *argv[] 

These variables can be used subsequently in the script The number of arguments 
(and therefore the number of elements in the array) is limited only by your UNIX 
script driver which generally imposes no practical limitation on script execution. 
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When a script is executed, the following variables are defined: 

argv[0] = the executable script name 
argv[l] = the log file name 



Arguments specified after the log file name in the script command are stored as 
argv[2], argv[3], and so on. You must specify a log file name if you want to 
specify other arguments. If you specify other arguments without specifying the log 
file, EMPOWER/CS will use the first argument as the log file name, thus creating an 
error. 



7.3.2 Argument Examples 

The following example illustrates a script execution: 

$ Bcriptl -d vagrant logl 1 3 wendy passwordl 

scriptl is the name of the binary script created by the Cscc tool. The option -d 
and vagrant specify that the activities will be displayed on the PC named vagrant, 
logl is the name of the log file that will be created when the script is executed. 
The parameters 1, 3, wendy, and passwordl are arguments that will be accessed 
during script execution. 1 and 3 will be used as arguments for EMPOWER/CS 
functions; wendy will be used as the log in ID; and workdir will be the emulated 
user's password. 



These arguments are accessed by the script through the variables argc and argv. 
The values of the variables are: 



argc = 6 
argv [ 0 ] = 
argv [ 1 ] = 
argv [2] = 
argv [ 3 ] = 



scriptl 

logl.l 

1 

3 



argv [ 4 ] = wendy 
argv[5] = passwordl 
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The source script file (the .c file) is edited to use these variables as in the following 
example: 

Thinkunif orm{ atoi (argv [2 ] ) , atoi { argv [3 ] ) ) ; 
Seed (atoi {argv[3] ) ) ; 

This example shows how the think time is varied in the script. The values of the 
variables argv [2] and argv[3] represent the limits of the think time distribution. 
The value of argv (3) also is used as the seed of the random number generator 
used to generate the sequence of think times. 

The variable array argv[] contains character string variables. Since the 
EMPOWER/CS functions Thinkuniform{ ) and Seed ( ) take integer arguments 
rather than character strings, you must use the C library function atoi ( ) to convert 
the character strings to integers. 

The resulting log file entries for the think time functions will be: 

Thinkuniformd .000, 3.000) 
Seed(3.000) 




7 A Script Variables 

EMPOWER/CS scripts are C language programs and therefore, you may use 
standard C variables in the script source file. All variables used in a script must be 
defined at the beginning of the script with the exception of argc and argv, which 
are defined automatically as described in the previous section. 
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Variables are defined with the int, char, float, and double C language 
statements. These statements define variables as follows: 

int - integer 

char * character 

float - single precision floating point 

double - double precision floating point 

These statements may be used to define several variables with the variables 
separated by commas. They also are used to define an array. The following 
examples show definitions of each variable type: 



int i, j , k; 
Q int i_array [ 10] ; 

char c; 

char product[20]; 
char *product_ptr ; 
float weight; 
double iq; 



In these examples, the variable array i_array contains ten integers, accessed as 
i_arfay[0] through i_array[9]. The product array can contain 20 characters. 
The variable *product_ptr is used to point to a character string. 

After variables are defined, they may be assigned values: 

i = 10; 

i_ array [3] = 17 

c = ' a ' ; 

iq = 17.325; 

product_ptr = "072148"; 



You also may define a variable and give it a value in one statement: 
int i = 11 

To use a variable in a script, simply reference it by name. 
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7.5 Editing Your Scripts 



After you have created a script with Capture, you likely will want to edit the script to 
change or add script functions. Of course, the changes you make to your scripts are 
driven by your testing goals but EMPOWER/CS scripts generally are edited to 
achieve the exact emulation environment desired. Because EMPOWER/CS scripts 
are actually C language programs, they can be edited to include branching and 
looping. Special EMPOWER/CS functions can be added to your scripts for 
advanced control of script execution. The following sections describe 
EMPOWER/CS functions that can be inserted into your scripts only by editing, and 
also describe methods for branching and looping. 



The Log() function records a message in the executed script's log file. Log{) 
functions are similar to comments in that they provide help in following the 
structure of a script. The parameter of the Log ( ) function must be a character 
string. 

The Noted function is used to place a note in the "Note" column of the 
EMPOWER/CS Monitor View 5 during script execution. The parameter of Note ( ) 
is a character string which is saved in the log file and subsequently displayed by 
Monitor. 

The inotet) function specifies a message that also will appear in the "Note" 
column of Monitor View 5. The parameter of inote ( ) is an integer that will be 
displayed by Monitor. 

You can insert these functions into your script as needed when you edit your script 



7.5.1 Recording Messages 



file. 
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7.5.2 File Input/Output Functions 

Creating scripts that read input files on the UNIX script driver is a common practice 
during load testing. Such input files may contain names, addresses, phone numbers, 
etc., that are used for emulating database queries and updates. EMPOWER/CS 
allows you to have a separate input file for each emulated user, or multiple users 
can share a single input file. Using a single input file is often more convenient since 
you do not have to maintain many files for large tests. 

EMPOWER/CS provides a convenient way for scripts to read from an input file, 
ensuring that data for each script is unique. The File I/O functions are used in 
scripts to read and write files which is useful for load tests requiring interaction 
with data files on the UNIX script driver machine. These capabilities also are useful 
in simplifying complex scripts such as database entry scripts. The EMPOWER/CS 
file input/output functions allow you to read data from a file, send data from the file 
to the SUT, receive data from the SUT ( and write those data to a file. These 
functions simplify the C language statements that would need to be added to 
accomplish the same thing. You can insert File Input/Output functions when editing 
your script 

The environment variable e_fiopath can be used to specify the directory in 
which the files to be accessed reside. A file must be opened before it can be 
accessed with the file input/output functions. Fioopen may be used to open a file. 
Also, the Fioreadline, Fioreadf ield, Fioreadchar, and Fiowritechar 
functions automatically open the file before reading from or writing to it. The 
function Fioshare is used to identify a file that is to be shared. If a file contains 
NULL characters, an error will occur when the file is read by an input/output 
function. 

Three global variables are used for file input/output. They are defined 
automatically as follows: 

unsigned char *FIOBUFFER 

int FIOLEN 

int FIOBUFFERSZ 
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The variable fiobuffer is a pointer to the characters read from the file. This 
variable often is used when sending data read from a file to the SUT. The variable 
fiolen is the number of valid characters in fiobuffer. If the value of fiolen is 
less than or equal to zero, then either an error occurred or the end-of-file was 
reached. The variable fiobuffersz is the maximum size of the data that can be 
read at one time. The default value of fiobuffersz is 512 characters. If the value 
of fiobuffersz is redefined in a script, it must be redefined before any file 
input/output functions that reference the file are encountered. 

The file input/output functions are: 

Fioseek 
Fioautorewind 
Fiorewind 

•ft 

J: These functions are described in the following sections. 

f 7.5.2.1 Fioshare 

m The syntax for this function is: 

O Fioshare ( filename) 

r=*r 

The Fioshare () function identifies a file that is to be shared. It must be called 
before any other File I/O functions are called to reference the same file. Fioshare 
in a script presumes execution of the fioshare command at the UNIX script 
drivers shell prompt. The fioshare command creates a global variable that 
contains the offset for the next byte to be read from a shared file. The value of the 
variable (offset) remains between tests, so you can continue to read an input file 
from the point left by the previous test. This saving of the offset is useful in tests 
that corrupt a database on the server. The ability to avoid the same transactions 
means you can avoid restoring the database before every test You must execute 
the fioshare command if you want to resume reading from the beginning of the 



Fioshare 

Fiounshare 

Fioopen 

Fioclose 

Fiodelimiter 



Fioreadline 
Fioreadf ield 
Fioreadf ields 
Fioreadchar 
Fiowritechar 



Fioskipline 
Fioskipf ield 
Fioskipchar 
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input file. For this reason, f ioshare is often run from Mix command files that set 
up for a new test. 

For example, assume we require scripts to read commands from an input file called 
cmds . The following command will create the global offset for the file: 

$ fioshare cmds 

A segment in the script to read from cmds might look like the following. Each 
instance of this script will read different lines. 



Fioshare ( n cmds " ) ; 

Fioreadline ( "cmds" ) ; 
if (FIOLEN == -1) 
{ 

Log ("end of the date file"); 
exit (1) ; 

} 

Type ( FIOBUFFER , M/ *M M , MM ); 



The global offset is stored in an EMPOWER/CS global variable. (Refer to the Multi- 
User Testing Manual for more information on global variables.) This global variable's 
name is the inode of the shared file. This can be confirmed by typing the UNIX 
"Is -i" command with an argument of the shared file and then running the 
gv_stat command, which lists the names, status, and value of EMPOWER/CS 
global variables. For example: 



$ fioshare cmds 




$ Is -i cmds 




59449 cmds 




$ gv_stat 




gv_stat: EMPOWER/GV VI. 0.0, 


Serial #R0000 0-000, Copyright PERFORMIX , 


Inc. 1988-95 




Name Type 


Value Allocated Protector 


59449 long int 


0 0 
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7.5.2.2 Fiounshare 

The syntax for this function is: 
Fiounshare { filename) 

The Fiounshare ( ) function discontinues the sharing of a file. The shell command 
fiounshare can also be executed to discontinue the sharing of a file. Neither the 
function nor the command remove the global variable offset for the file. They 
simply mark the global variable as being unusable for further input/output 
functions. 

The Fiounshare function disables the sharing of the file offset only for the script 
that executes the function and the fiounshare shell command disables the sharing 
of the file offset for all scripts currently sharing the file. 

To remove the global variable offset, you must use the gv_rm shell command to 
remove the variable named in the gv_stat output listed above. For example: 

$ gv_rm -f 59449 



7.5.23 Fioopen 

The syntax for this function is: 
Fioopen { filename, mode) 

The Fioopen () function opens the file filename. The parameter mode specifies 
how the file is opened. If mode is V, the file is opened at the beginning for 
reading only. If mode is "w", the file is truncated or created for writing only. If mode 
is "a", the file is opened at the end for writing only. If mode is M r+ M ( the file is 
opened at the beginning for reading and writing. If mode is V+" f the file is 
truncated or created for reading or writing. If mode is "a+", the file is opened at the 
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end for reading and writing. If the function is successful, zero is returned. If an 
error occurs, -1 is returned. 



7.5.2.4 Fioclose 

The syntax for this function is: 

Fioclose ( filename) 

The Fioclose ( ) function closes the file filename. If the function is successful, 
zero is returned. If an error occurs, -1 is returned. 

7.5.2.5 Fiodelimiter 

The syntax for this function is: 

Fiodelimiter ( filename, delimiters ) 

The Fiodelimiter ( ) function defines the field delimiters for the file filename. 
The default is "\t\n" and "\n M is always a delimiter ("\t" is tab and "\n" is new line 
or linefeed). If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

7.5.2.6 Fioreadline 

The syntax for this function is: 
Fioreadline ( filename) 
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The Fioreadline ( ) function reads the next line from the file filename into 
fiobuffer. If the file is not currently open (see Fioopen), it is opened 
automatically. A pointer to fiobuffer is returned. If fiolen is less than or equal to 
zero, then either an error occurred or the end-of-file was reached 



73.2.1 Fioreadfield 

The syntax for this function is: 

Fioreadfield { filename) 

The Fioreadf ield( ) function reads the next field from the file filename into 
fiobuffer. The fields are separated by the delimiter (see Fiodelimiter). If the file 
is not currently open (see Fioopen) t it is opened automatically. A pointer to 
fiobuffer is returned. If fiolen is less than or equal to zero, then either an error 
occurred or the end-of-file was reached. 



7.5.2.8 Fioreadfields 

The syntax for this function is: 

Fioeadfields ( filename, n, argO, arg[n]) 

This function reads n fields from the file filename as delimited by field delimiters. 
(The default is " \t\n" , where "\n n is always a delimiter.) Fields are copied into 
arguments. If the specified file is not currently open, this function automatically 
opens it for reading. 

The Fioreadfields ( ) function returns a pointer to fiobuffer 



EMPOWER/CS-Vl.0.1 



7- 61 




Copyright PERFORMIX. Inc. O 1995 




User's Guide— Script Development 



7,5.2.9 Fioreadchar 

The syntax for this function is: 

Fioreadchar ( filename, n) 

The Fioreadchar { ) function reads n bytes from the file filename. If the file is 
not currently open (see Fioopen), it is opened by Fioreadchar () . A pointer to 
fiobuffer is returned. If fiolen is less than or equal to zero, then either an error 
occurred or the end-of-file was reached. 



7.5.2.10 Fiowritechar 

The syntax for this function is: 

Fiowritechar ( filename, buf, n) 

This function writes n bytes from the buffer, buf, to the file filename. If the file is 
not currently open (see Fioopen), it is created or truncated and opened for reading 
and writing automatically. If the function is successful, zero is returned. If an error 
occurs, -1 is returned. 



7.5.2.11 Fioskipline 

The syntax for this function is: 

Fioskipline ( filename, n) 

The Fioskipline ( ) function skips forward n lines in the file filename. If the file 
is not currently open (see Fioopen), it is opened automatically. The variables 
fiobuffer and fiolen are updated with the last line read. If the function is 
successful, zero is returned. If an error occurs, -1 is returned. 
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7.5.2.12 Fioskipfield 



The syntax for this function is: 

Fioskipfield ( filename, n) 

The Fioskipf ield( ) function skips forward n fields in the file filename. The 
fields are separated by the delimiter (see Fiodelimiter). If the file is not currently 
open (see Fioopen), it is opened automatically. The variables fiobuffer and 
fiolen are updated with the last field read. If the function is successful zero is 
returned. If an error occurs, -1 is returned. 



The syntax for this function is: 
Fioskipchar ( filename, n) 

The Fioskipchar ( ) function skips forward n characters in the file filename. If the 
file is not currently open (see Fioopen), it is opened automatically. The variables 
fiobuffer and fiolen are updated with the last characters read (the number of 
characters used to update fiobuffer and fiolen is defined by the variable 
fiobuffersz). If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



The syntax for this function is: 

Fioseek ( filename, offset) 

The FioseeM ) function sets the file pointer to a specific byte in the file. The next 
byte read or written will occur at offset bytes from the beginning of the file. If the 
value of offset is equal to fioend, the seek will occur to the end of the file. If the 
function is successful, zero is returned. If an error occurs, -1 is returned. 



7.5.2.13 Fioskipchar 



7.5.2.14 Fioseek 
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7.5.2.15 Fiorewind 

The syntax for this function is: 

Fiorewind ( filename) 

The Fiorewind ( ) function rewinds the file pointer to the beginning of the file for 
the file filename. If the function is successful, zero is returned. If an error occurs, 
-1 is returned. 



75.2.16 Fioautorewind 

The syntax for this function is: 

Fioautorewind ( f i lename ) 

The Fioautorewind ( ) function automatically rewinds the file pointer to the 
beginning of the file specified in filename, whenever the end-of-file is 
encountered. This function is useful if multiple scripts read data from one file. 



75.2.17 File Input/Ouput Function Examples 

The following example illustrates using the functions Fioreadf ield { ) and 
Fioreadf ields ( ) to read one or more fields from a file. Fiodelimiter ( ) is used 
to specify that the field delimiter in the file input file is a comma. 
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char last [20] ; 
char first [20] ; 



Fioopen ( " inputf ile" , "r"); 
Fiodelimiter ( " inputf ile " , ■ , " ) ; 
Fioreadf ield{ M inputf ile" ) ; 
Type( "%s" # FIOBUFFER) ; 

LeftButtonPress (360, 211) ; 

AppWait (0.06) ; 
WindowRcv( M Sf Sf Pt" ) ; 

Fioreadf ields ( "inputf ile M , 2, last, first); 
Type( M %s tt , last); 

LeftButtonPress (357, 252) ; 



AppWait (0 . 06) ; 
WindowRcv( M SfSfPt M ) ; 

Type("%s M , first); 



The following is a portion of the file inputf ile: 



312890463 
doe, jane 
294028190 
smith, john 
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The following examples show you how to use the rewind functions to reuse data in 
an input file. Notice that Fioautorewind{ ) saves you some programming time 
because you do not have to check to see if you are at the end of the file: 



Fioautorewindf " info" ) ; 
Fioreadline ("info") ; 
Type{"%s" f FIOBUFFER); 



OR 



Fioreadline { M info " ) ; 
if (FI0LEN==-1) { 
Fiorewind( "info" ) ; 
Fioreadline { " info" ) ; 
} 

Type{"%s M , FIOBUFFER); 



7.5.3 Pacing Functions 

EMPOWER/CS allows you to insert three functions into your script file for 
controlling the pace of the script These pacing functions cause the script to pause 
long enough to make the script send transactions to the SUT at a predetermined 
throughput. Typically used in a loop, these functions may be nested to permit 
controlled throughput of transactions within a larger transaction. 

Each of the pacing functions accepts an argument naming the pace and defining 
the speed of the pace. 

Paceconstant ( ) causes transactions to be submitted at a constant throughput The 
second argument to Paceconstant ( ) defines the number of seconds that the 
script should take since the last call to Paceconstant ( ) . The first call to a pacing 
function does not delay; it is used as a starting point for the subsequent calls. For 
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this reason, the first call to a pacing function is often made with arguments of 0 to 
define the speed. 

Paceunif orm( ) and PacetneO control throughput but do not do so at a constant 
rate. The functions have an average throughput that will be maintained, but 
submission of transactions occurs at frequencies other than that defined by a 
constant distribution. 



Paceunif orm{ ) accepts two arguments to identify the speed of the pace - a 
minimum delay and a maximum delay. The average of the two will be maintained 
during sustained execution of the script Each time Paceunif orm( ) is executed, it 
will delay for a number of seconds since the last execution, where the number is 

4f taken from a uniform distribution between the minimum and maximum values. For 

f£„ example, if Paceunif orm( "query" , 8.0, 12.0) is used in a script, a sequence 

of 9, 11, 8, 10, and 12 second delays is possible (assuming the query has a response 

'"4 time of zero seconds.) The average of the delays is still ten seconds. 

Paceunif orm( ) will select the values for delay accurate to l/100th of a second, so 

jS 9.27 seconds is a possible value. 

H Pacetne ( ) accepts three arguments to identify the speed of the pace - a minimum, 

?J average and a maximum delay. The average will be maintained during sustained 

execution of the script Each time Pacetne ( ) is executed, it will delay for a number 
O of seconds since the last execution, where the number is taken from a truncated, 

w negative exponential distribution defined by the three values. In a typical such 

distribution, the average is relatively close to the minimum. For example, if 
Pacetne ( "query", 7.0, 10.0, 20.0) is used in a script, a sequence of 7, 8, 10, 
and. 15 second delays is possible. The average of the delays is still ten seconds. 
Pacetne { ) will select the values for delay accurate to l/10th of a second, so 9.2 
seconds is a possible value. 
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7.5.4 Advanced Use of Script Variables 

Five EMPOWER/CS functions exist that allow you to manipulate script variables. 
They are CmpVar ( ) , GetVar ( ) , GetlntVar { ) , SetVar ( ) , SetlntVar ( ) . These 
functions allow you to test, update, read, and compare variables. 

You may insert the CmpVar ( ) function into your script to compare a variable from a 
SQL statement to a specified value. The syntax for this function is: 

CmpVar (curnum, var, value) ; 

This function determines if the specified variable, var, in the current row is equal 
to the value specified in the value parameter. The address of the variable must be 
passed to CmpVar ( ) . 

This function could be used for fetching records until a certain value is returned. 
An example of this function follows: 



Parse{CURl, "select ename from employee_table " ) ; 
Define (CUR1, "1", STRING , 50); 
Exec (CUR1) ; 

Dbset(CURl, FETCHSIZE, 1); 

while {CmpVar (CUR 1, M l", "Smith") != 0) { 

Fetch(CURl); 

GetNextRow(CURl) ; 



You can insert the GetVar { ) or GetlntVar { ) functions into your script to return 
the current value of a specified variable (either the name or the position) in the 
SQL statement. GetVar ( ) is used for string variables and GetlntVar ( ) is used for 
integer variables. These functions should be inserted into the script after the 
Fetch ( ) and GetNextRow( ) functions. 
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The following example demonstrates using the GetVarO function within a script 



char * empname, * empno; 



Parse(CURl, "select ename, empno from employee_table " ) ; 

Define (CUR1, "1", STRING , 50); 
Define (CUR1, "2 M , INT, 4); 

Exec (CUR1); 



Dbset(CURl, FETCHSIZE, 1) ; 
while (Fetch(CURl) != 0) { 

GetNextRow (CUR1 ) ; 

empname=GetVar (CUR1 , " 1 ■ ) ; 

printf ( "empname is %s\n" , empname) ; 

empno=GetVar (CUR1, "2" ) ; 

printf ( "empno is %d\n" , Mint *) empno ) ; 

} 



The SetVarO and SetintVarO functions assign a new value to a specified 
variable. The syntax for these functions follows: 

SetVar (curnum, var, value); 
SetlntVar (curnuro, var, value); 




The new value for the variable, var, is assigned in the parameter value. These 
functions could be inserted into the script before an Exec ( ) function or after the 
GetNextRow{) or GetVar ( ) functions. 
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The following example demonstrates using Setintvar ( ) in a script: 



int empno , deptno , i ; 



Parse (CUR1, "select ename from employee_ table where empno =: empno 
and deptno= : deptno" ) ; 

Bindp(CURl # 1, INT, 4); /* pos 1 is : empno */ 

Bindp(CURl, 2, INT, 4); /* pos 2 is : deptno */ 

Data(CURl, "23 |20") ; 



empno=GetIntVar (CUR1, "1"); 
deptno=GetIntVar (CUR1, B 2); 



/* keep executing above parse statement changing the empno 

every time */ 

for (i=0; i<5 ; i++) { 

empno = empno +i ; 

SetlntVar (CUR1, w 2" # empno); 



Exec (CUR1) ; 



if .< Fetch (CUR1) != 0) 

print f (" empno %d is in deptno %d\n" , empno, deptno) 

else 

pr int f ( "empno %d is not in deptno %d\n w , empno, 

deptno) ; 
} 
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7.5.5 Looping 

EMPOWER/CS scripts may be modified to contain loops controlled by the standard 
C language for and while statements. You can use a loop to emulate hour long 
activity instead of having to capture activity for an hour. The for statement 
executes a set of EMPOWER/CS functions a fixed number of times. The while 
statement executes a set of EMPOWER/CS functions as long as a given condition 
is satisfied. 

You must insert loops very carefully if you plan to execute scripts in both Non- 
Display and Display modes. You must be sure to encompass all relevant functions 
in the loop for Non-Display and Display script execution. For example, you must 
include all relevant button presses within the loop so that the correct sequence of 
buttons will be activated during script execution in Display mode. 

For your convenience, you should insert a comment or function in the script to 
mark where you wish to begin and/or end looping. 



7.5.5.1 Looping with the For Statement 

Executing a loop a certain number of times in a script is accomplished with the for 
statement The syntax of the for statement is: 

for {initial; condition; step) 
{ 

/* body of the loop */ 

} 

The parameter initial generally contains the initial assignment of a looping 
variable. The parameter condition specifies the condition under which looping 
should continue. This condition is evaluated every time the loop is about to be 
entered. The parameter step generally specifies the increment or decrement of the 
looping variable. Note that the body of the loop is contained between braces, { } . 



EMPOWER/CS-Vl.0.1 



7-71 

Copyright PERFORMIX, Inc. 0 1 995 



User's Guide— Script Development 



7.5.5.2 Looping with the While Statement 

The while statement is used to execute a loop in an EMPOWER/CS script as long 
as a given condition is satisfied. The syntax is listed below: 

while (condition) 
{ 

/* body of the loop */ 

} 

Each time the loop is entered, the condition specified in the parameter condition 
is tested. If the condition is met, the loop is executed. If not, script execution 
^ continues past the loop. 

01 

yj The following example demonstrates a common while loop used within 

Sj EMPOWER/CS scripts: 

Fetch (CURl); 

==? 

s while (GetNextRow(CURl) ! =NOMOREROWS ) ; 

□ 
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8.0 EMPOWER/CS Tools 

EMPOWER/CS offers four Windows features under the Tools icon. These Tools 
are XY, Modules, Transfer, and Tree. 

When you activate Tools in the EMPOWER/CS window, the following window 
opens: 



Empower/CS 



Tools 



HI 

Capti 



File Help 





- 

ID! 




XY. 









Modules... 




Transfer... 



Tree... 



8.1 XY 

If you wish to add or change mouse button events (i.e., Lef tButtonDown ( ) , 
Lef tButtonUp ( ) , RightDblPress { ) , etc.) in the script file, you will need to know 
the on screen xy coordinates of the locations that are to be activated. The XY tool 
helps you to locate on screen xy coordinates of the PC mouse. 
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Activate the XY pushbutton. The following window appears displaying the current 
xy coordinates of your mouse: 




r*3 



The Trace option of this tool follows your mouse movements listing the on screen 
xy coordinates as the mouse moves. If you de-select Trace, you can type a number 
in the left field that will move the mouse to that x position on screen. If you tab to 
the next field, you can enter a y position that will move the mouse to that y position. 
As you type each number, the mouse will move to the specified position. 



Select Exit from the File menu to close this tool. 



8.2 Modules 



Select the Modules button to activate the following window: 
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Modules 



c:\windows\progman.exe (1) 
c:\windows\system\comm.drv (26) 
c:\windows\system\cornmdlg.dll (1 3] 
c:\windows\system\coure.fon (1) 
c:\windows\system\gdi.exe (26) 
c:\wi n d o ws\sy ste m\key b o a rd . d rv (2 8) 
c:\windows\system\krnl386.exe (34) 



OK 



Update 



This tool alphabetically lists all the processes currently running in Windows. The 
number listed in parentheses indicates how many instances of the process are 
running. Update updates all process information. 

The Modules tool can be used for debugging. For example, if you encountered an 
error when trying to Capture client/ server activity, you could use Modules to verify 
that winsock.dll is installed on your PC. 

Select OK to exit this tool. 



8.3 Transfer 

The Transfer tool allows you to transfer files manually from the PC to the UNIX 
script driver. 



Select the Transfer pushbutton in the Tools window. The following window will 
open: 
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Transfer 



File 



exl.c 



Type ® Ascii O Binary 



Host 
Username 

Password 
Remote Directory 



indy 



john 



******** 



/temp 



OK 



Cancel 



Browse. 



Enter the complete name of the script or data file you wish to transfer and specify 
in what form you wish to transfer the file, either as ASCII or Binary. 

In DOS files, an end-of-line includes a carriage return and a linefeed whereas in 
UNIX an end-of-line requires only a linefeed. Transferring a file as ASCII translates 
the carriage return/linefeed combinations in a DOS file to the single linefeed 
required in UNIX. 

If you specify Binary, the file is transferred without character translations. 
Therefore, you should specify Binary for transferring files in which data can not be 
altered and all characters are required for the file (i.e., images). 

If large amounts of data (i.e., images, large text files, etc.) are input to the database 
during Capture, such data is inserted into separate data files. If you are transferring 
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a script that has data files, you must transfer the associated data files separately in 
Binary mode. Scripts should be transferred as ASCII files. 

If you need to locate a file, select the Browse pushbutton in the Transfer window to 
browse all available directories. 

The following Browse window will open: 



File Name: 



diffem.c 

k.c 

r.c 



List Files of Type: 



Scripts(*.c) 



Select File(s) 



Directories: 
c:\empower\cs\t 



&c:\ 

£> empower 

&cs 



Drives: 



OK 



Sic: 



Cancel 



Network. 



□ Read Only 



In this window, you may specify or search through all available directories, files, and 
disk drives. You may select multiple files from a specific directory. When you have 
located all needed files, choose OK or Cancel as appropriate to return to the 
Transfer window. 



After specifying a file, you should enter the Host name (the UNIX driver), the 
appropriate Username and Password, and the Remote Directory (on the UNIX 
driver) where you wish to transfer the script file. 

In the Transfer window, select OK to transfer the specified file to the UNIX driver 
machine. 
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If the script .c file already exists on the UNIX driver, you will receive the following 
message: 



Warning 



Script 'exl .c' exists on 'indy', overwrite 



lOKi 



Cancel 



Choose OK or Cancel as appropriate. 



8.4 Tree 

The Tree tool allows you to list the tree structure for a MS Windows pushbutton, 
such as OK, Cancel, Yes, No, etc. 



This tool can be used if you wish to manually insert or change a ButtonPush ( ) 
function. It allows you to determine the tree structure for the ButtonPush ( ) 
function's str parameter. 



8.4.1 The Tree Structure 

The MS Windows tree structure is based on a heirarchy of windows where each 
window that is accessed from a primary, or parent window, is a child of that parent 
For instance, each window or pushbutton that is activated from another window is a 
child of the window it opens from. If two or more equal level windows are 
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accessible from a parent window, they are children of that parent window and 
siblings of each other. 

The following diagram demonstrates this structure: 




3rd child of C1 



The Tree tool lists a tree structure from right to left, from child to parent, where the 
right-most item is the name of the button or window you selected. If one of the 
windows or the pushbutton has no title, something like M #c1 M will be listed to 
indicate the window or pushbutton is a certain numbered child of the preceding 
parent window. 

Mote: In some rare cases, applications are designed where a window requires its 
sibling window to also be its parent in which case something like "#s1 M may be 
listed in the structure. 

A tree structure from the above diagram could look like: W1|#c1|#c2. In this 
example, #c2 is the second child of the first child (#c1) of the window W1. 
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In the following tree structure, Tools|WindowTree|Cancel, Cancel is the button 
contained in the window WindowTree which is a child of the Tools window. 



8.4.2 Using the Tree Tool 



Select the Tree button from the Tools window which opens the following window: 



Window Tree 



Tree 



Cancel 



Activate the Tree button. The mouse pointer will turn into a large arrow. 

With this new pointer, select the button for which you wish to list the Tree 
structure. This tree structure is listed in a particular heirarchy as explained above in 
Section 8.4.1. 

As an example, obtain the Tree structure for the Cancel button, by selecting Tree. 
Then, select Cancel in the Window Tree window as shown below: 

The following structure will appear in the Window Tree window: 

Tools|Window Tree|Cancel 



When you have obtained all needed tree structures, select the Cancel button or 
Close from the WindowTree window's System menu. 
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